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Part 1 


Introduction to Turbo Pascal 


The original Pascal language was created by Nicklaus Wirth as a teaching language: 
a device for demonstrating and teaching the principles of computer programming. 
But, because he designed Pascal from scratch, Wirth was not bound by the many 
constraints and complexities that had plagued earlier languages. He was free to 
design his language for convenience as well as powerful programming capabilities. 
The resulting focused and practical design has since been emulated by many other 
languages, such as Ada, the government/military programming compiler, Mod- 
ula2, and even the perennially popular C. 

Convenience and power are only part of the programming story. Spreadsheets, 
for example, such as Quattro or Lotus, are convenient and, within their design 
capabilities, provide a lot of programming power. But they are also limited to 
specific application types and even a powerful spreadsheet does not provide a 
platform for writing an editor or a game program or a point-of-sale/inventory 
package. 

Turbo Pascal, on the other hand, provides convenience without being limited 
to a specific application type. In fact, Turbo Pascal allows you to create any 
application you can imagine and design. And, more important, Turbo Pascal 
provides you with the tools and capabilities to design powerful applications with 
excellent execution speed. 

But even power and speed are not the final consideration, because the most 
important element of all is how long it takes for you to create your application. And 
this is where Turbo Pascal is unparalleled! 
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Turbo Pascal provides not only an efficient compiler language, but an efficient 
programming environment that includes an interactive editor, complete on-line 
help features, and superb function libraries, complete with virtually every tool 
imaginable. Most of the time, these will be the only features you will need. 

The real test of a compiler, however, comes not when your programs work but 
when they don’t work. A compiler is a tool, not a magic genie, even though it might 
feel rather like one at times. Often, the better your programming becomes, the 
sooner you find yourself writing programs that almost, but not quite, do what you 
intended. And here is where Turbo Pascal can work "magic," by providing debug- 
ging capabilities when you need to find out why things aren’t working quite the 
way you envisioned them—or just want to find out how a program works. 

Finally, when you really get serious about wringing the last iota of performance 
out of your programs, Turbo Pascal supports Borland’s standalone products, Turbo 
Assembler, Turbo Debugger and Turbo Profiler, which provide the programmer’s 
equivalent of a custom speed shop, analytic test bench and test track. 

But, before worrying about how many performance limits you can break, you 
must learn how to create programs and learn how to create them well. 

A program can be judged by three criteria: 


= How well does it work? 
« How easy is it to understand and use? 
= How does it look? 


If you have been around computers for any length of time you have surely 
encountered programs that executed well and looked fancy but were hard to use, 
and you wished they worked just a bit differently. And you have probably seen 
programs that were easy to understand but didn’t show you everything you 
wanted to see. And you may have seen programs that looked nice and were easy 
to use, but were frustratingly slow. You may well have run across one or two that 
suffered from all of these faults. ; 

Well, this is your chance to have it all and have it your way. This book will show 
you how to use Turbo Pascal 6.0 to write programs that run the way you've always 
known they should, and have always imagined they could. 

Now, is this incentive enough? 


Chapter 1 


Installing Turbo Pascal 6.0 


Installing Turbo Pascal 6.0 is probably the easiest job you'll ever do on a computer, 
and, at the same time, it should give you an idea of how easy Turbo Pascal is to use. 
You can install Turbo Pascal either on floppy disks or your hard drive, using 
either drive A: or drive B: for the installation source file. Turbo Pascal 6.0 is normally 
distributed on four 5 1/4” floppy disks, although you can request 3 1/2” disks. 
In either case, the first step is to insert the Install/Compiler disk in either the A 
or B drive and then, from the DOS prompt, call the installation program: 


A:>INSTALL , 


After this point, the INSTALL program handles almost everything, requesting 
only information concerning the type of installation desired. 

Initially, the installation utility presents the display shown in Figure 1-1. To 
continue, simply press ENTER. 

The next screen, shown in Figure 1-2, asks you to confirm the source drive 
where the Turbo Pascal distribution disks can be found. The assumption is that the 
active drive—drive B in the illustration—where the Install program was called, is 
the drive used. If necessary, however, you can specify an alternate source drive. 

The next step is to inform the Install program whether you intend to install 
Turbo Pascal on a floppy drive or a hard drive. While a hard drive is the default 
assumption, since most programmers today have hard disk systems, Turbo Pascal 
can be installed in a limited format on floppy drives. 

Note: Two floppy drives are required for floppy disk installation. 
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Turbo Pascal 6.6 Installation Utility 


Copyright (c) 1988, 1996 by Borland International, Inc. 


Install Utility Version 1.6 
Welcome to the Turbo Pascal installation program. 
This program will copy all files needed to install and run 
Turbo Pascal on your system. 













Press ENTER to continue, ESC to quit. 


Figure 1-2: Selecting the Installation Source Drive 





()| turbo Pascal 6.0 Installation Utility |} ce 


IHEP ARE —- Description —-—- nn 
Enter the drive that contains the Turbo Pascal distribution disks. 
This drive will be used to do all the copying. 





" “Select Cancel 


Installing Turbo Pascal on Two Floppy Drives 


Figure 1-3 shows installation selected for floppy drive. Next, the Install program 
asks if you want to install the Integrated Environment or the Command-Line 
compiler, as shown in Figure 1-4. Unless you are an experienced programmer—in 
which case you probably will not be reading this chapter—the Integrated Environ- 
ment is strongly recommended. 

For installation of the Integrated Environment, two floppy disks are required: 
either 3 1/2”, 720K or 1.4 megabyte, or 5 1/4”, 360K or 1.2 megabyte are acceptable. 
You should label the two disks Turbo Pascal Compiler Disk and Turbo Pascal 
Library Disk. 


Chapter 1: Installing Turbo Pascal 6.0 5 





Figure 1-3: Selecting Floppy Disk Installation 

f#| Turbo Pascal 6.6 Installation Utility 
Install Turbo Pascal on a Hard Drive 
ae 








—HH/)HMTVMNOQZt=NQN iin nantes uid 

This option will install Turbo Pascal on a floppyu-based sustem. Note that 
you must have two floppy drives to use this installation program. 

You need one blank, formatted disk ready to install the command-line 
compiler. You need two blank disks to install the Integrated Development 
Environment . 





—Help ~Select —-Previous 


Figure 1-4: A Choice of Compilers 





i! Turbo Pascal 6.0 Installation Utility | 
Install Turbo Pascal on a Hard Drive 


ij) Install Turbo Pascal Integrated Environment |}! 
Hi Install Turbo Pascal Command-Line Compiler 


fn na We De SCLiption wn 
This option will install Turbo Pascal’s Integrated Development Environment 
for a two-floppy system. It requires two blank, formatted floppy disks, 
which will be referred to as: 
Turbo Pascal Compiler Disk 
Turbo Pascal Library Disk 
Selecting this option will start copying files onto your floppy disk. 
These floppies MUST be completely empty: do not use the ¢S option when 
formatting them. 
Note that you must have two floppy drives to use this installation progran. 


—Help —-Select 








—-Previous 


After labelling them, insert each disk in the destination floppy drive as 
requested by screen prompts. The Pascal compiler, TURBO.EXE, will be unarchived 
and copied to the compiler disk, and the default library, TURBO.TPL, will be 
unarchived and copied to the library disk. 
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When finished, the Install program displays the screen shown in Figure 1-5. At 
this point, one modification to the CONFIG.SY$ file on your boot disk is suggested. 
Add the line: 


FILES=20 


If your compiler disk has been formatted as a boot disk, add the FILES 
command to the CONFIG.SYS file on this disk, or, if you are using a different disk 
to boot, make this modification wherever appropriate. 

At this point, with the compiler disk in A: and the library disk in B:, you can 
execute the Turbo Pascal Integrated Environment compiler by typing: 


A:>TURBO , 
Note: For the command-line version of the compiler, refer to the Turbo Pascal 


manuals for the appropriate command-line switches and options. 


Figure 1-5: Floppy Disk Installation Complete 





Turbo Pascal is now installed. Make sure the 
line: 


FILES=20 
is in the CONFIG.SYS file on your boot disk. 
To use Turbo Pascal, place the “Turbo Pascal 
Compiler Disk" into the drive B: and the ‘Turbo 


Pascal Library Disk" into drive A: (make sure 
you're logged onto drive A:). Then type B: TURBO 


Press any key to continue. 





Modifying the Floppy Disk Installation In actual fact, a single 720K, 1.2 megabyte 
or 1.4 megabyte disk is more than ample to hold both the compiler (TURBO.EXE) 
and the Pascal library (TURBO.TPL) with adequate space remaining for program 
source codes. However, the Install program insists on installing these on separate 
disks. After installation is completed, of course, you are perfectly free to copy the 
TURBO.TPL library file to the compiler disk. 

For floppy drive installation, the Turbo Pascal unit libraries, example programs, 
.BGI files and Turbo Vision files are not installed, but can be unpacked individually, 
as needed, using UNZIP.EXE or any compatible archive utility. 
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The Turbo Pascal help file (TURBO.HLP) requires 627K of disk space, which 
would leave very little development space on most floppy drive systems. 
TURBO.HLLP is archived as HELP.ZIP. 

The Turbo Tour utility provides a hands-on tutorial with instruction in the 
principal features of the Turbo Integrated Environment. Turbo Tour is archived as 
TOUR.ZIP and requires 285K of disk space, including the .CBT files. The Tour 
facility should be unarchived on a separate disk, not included on the compiler disk. 
Type TPTOUR to use the tutorial. 


Installing Turbo Pascal on a Hard Drive 


Figure 1-6 shows hard drive installation selected. Installation on a hard drive 
requires one floppy drive for the source files and approximately 3.5/4.0 megabytes 
of free space on your hard disk. 

Hard drive installation copies all source files, including both the Integrated 
Environment compiler (TURBO.EXE) and the command-line compiler (TPC.EXE), 
the help facility (TURBO.HLP—627K) and the Turbo Tour program (TPTOUR.EXE 
plus data files—285K). 


Figure 1-6: Selecting Hard Disk Installation 








Turbo Pascal 6.6 Installation Utility 


pa wate a — 
Install Turbo Pascal on a Hard Drive I] 


| inetall Turbo Fascal | on a a Floppy Drive: || 


a —_——-— Description eens i aan 
hank) Pils Deanat to your hard drive. This option requires ieee 3. a. 
magahytes of free space on your hard drive. 





—Help -Select -Previous 
Other files include document files, demonstration programs for both the new 
Turbo Vision object hierarchy (\TP\TVDEMOS) and for conventional Pascal 
(\TP\DEMOS), documentation for demo programs (\TP\DOCDEMOS), unit 
libraries (\TP\UTILS), the Borland graphics interface (\TP\BGI) and compatibility 
libraries for programs originally written under Turbo Pascal 3.0 (\TP\TURBOS3). 


The default subdirectories for each of these are shown in Figure 1-7. 
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Figure 1-7: Hard Drive Directory Options 


Turbo Pascal 6.6 Installation Utility | 


Turbo Pascal directory: 

Turbo Vision directory: 

Turbo Vision Demos directory: 
Documentation Demos directory: 
Demos directory: 

Documentation directory: 


:-NTPNTVISTION 
>NTPNTYDEMOS 
:NTPNDOCDEMOS 
:-\NTPNDEMOS 
-NTPNDOC 
>-\NTPNBGI 
-NTPNUTILS 

:-N TPN TURBOS 

s 


Graphics directory: 

Utilities directory: 

Turbo Pascal 3.6 Compatibility directory: 
Unpack additional archives: 


COoaaagagag Oe 


Start Installation 


————_. $$ —__—__——————- Description 
Press ENTER to change the directory for all Turbo Pascal sustem files. This 
includes the program, help, and configuration files. This directory acts as 
the base directory for the subdirectories below. Changing this one will 
change the rest correspondingly. 











—Help -Start Inatatiation -Select -Previous 
The Install utility assumes that installation will be made to drive C:, but you 
can select any valid hard drive or logical partition and directory by highlighting 
the first item and pressing ENTER. This calls a dialog window where you can enter 
a new drive and directory specification. 
Changing the first entry in the directory display changes the drive and sub- 
directory specifications for all of the remaining directory specifications, as shown 


in Figure 1-8. 


Figure 1-8: Changing Drive and Directory Specifications 











> \ TURBO 
:NTURBONTYV IS ION 
>: \NTURBON TUDEMOS 
: NTURBONDOCDEMOS 
: NSTURBONDEMOS 

: NSTURBONDOC 

: \NTURBONBG I 

> \TURBONUTILS 

: \STURBOSN TURBOS 
es 


Turbo Pascal directory: 

Turbo Vision directory: 

Turbo Vision Demos directory: 
Documentation Demos directory: 
Demos directory: 

Documentation directory: 


Graphics directory: 

Utilities directory: 

Turbo Pascal 3.6 Compatibility directory: 
Unpack additional archives: 


ceeeoere so 


Start Installation 











Other subdirectory paths can be individually altered by highlighting the exist- 
ing entry, pressing ENTER and providing a new specification. The default paths 
are recommended, however. 

The next to last item on this screen, Unpack additional archives, can be toggled 
by pressing ENTER. If space is a consideration, this option can reduce your space 
requirements to approximately 2.0 megabytes. If archives are not unpacked, the archive 
files are still copied to the appropriate directories and may be individually 
unarchived later, using the UnZip utility in the Turbo Pascal root directory. 

Select the final menu entry, Start Installation, and press ENTER (or, alterna- 
tively, press the F9 key) to initiate installation, unpack the archived files and copy 
them to the appropriate directories. Directories and subdirectories will be created 
as needed. 

At this point, simply follow the screen prompts, as shown in Figure 1-9, 
inserting the appropriate disks as requested. 

The window at the bottom of the screen (Figure 1-9) does list the current action 
being taken by the Install utility but does not require any response. 


Figure 1-9: Screen Prompts 








Please insert your 
TURBO VISION/TOUR 
disk into drive B: 
{| Press any key to continue 
B:\SREADME.COM, B:\UN ao 
Writing files: 
C:NTPNREADME .COM, C:NTPNUNZIP. EXE 
Executing: 
CINTPNUNZIP.EXE ~o BiINTURBO.ZIP C:NTP 
Reading files: 
B: \SREADME 0 
Writing files: 
CiNTPNREADME 





—-Cancel 


When installation is completed, the message box shown in Figure 1-10 suggests 
two modifications. The font modification has already been mentioned—add to 
your CONFIG.SYS: 


FILES = 20 


The second modification is to include two Turbo Pascal path specifications in 
the PATH command in your AUTOEXEC.BAT file: 
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PATH Vee Aes Ce TR Cas 


After specifying the directory path, you can call the Turbo Pascal Integrated 
Environment from the DOS prompt: 


C:>TURBO , 


Note: For the command-line version of the compiler, refer to the Turbo Pascal 
manuals for the appropriate command-line switches and options. 

Once you've finished installing Turbo Pascal on your system, put the source 
disks away in a safe place—just in case, for any reason, you need to reinstall your 
compiler. Now that installation is finished, the final section of this chapter presents 
a suggestion for setting up your system. 


Figure 1-10: Hard Drive Installation Completed _ 





The Turbo Pascal 6.0 installation is now 
complete and selected files have been copied 
onto your hard drive. To read about last minute 
changes to the documentation, tyupe README and 
press ENTER. After reviewing the README file, 
you may wish to customize Turbo Pascal for your 
system by loading TURBO.EXE and using the 
Options menu. For more information, refer to the 
IDE reference chapter in the User’s Guide. 


Make sure the line 

FILES = 260 
is in your CONFIG.SYS file, and 
C:NTP;C:NTPNUTILS is in your path. For example, 
to run any of the Turbo Pascal programs or 
utilities from anywhere on your system, your 
AUTOEXEC .BAT file could contain a path like the 
wep @ cel hei me 

PATH=SC (NDOS:;CINTPIC:INTPNUTILS 


Press any key to continue. 





An Alternate Path Command 


Today, it seems as though every program you install expects to have one or more 
directories included in the PATH specification. Unfortunately, this can result in a 
PATH specification that reads like this: 


PATH CeNsCseNDOS;C:\HOTS Cs \MOUSESCeV\QEMMsCs\TASMSCI\TC: 
CoANTCNBINZ CENTOS CEN FP sCeNTRNUTILE sC2ATRPROES Cs \KXBAT?Ds\ 


FB;D:\INTEGRA\BIN;D:\PARADOX;D:\WORD5;D:\QUATTRO;D:\WP; 
D:\WW> 
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But when your PATH command exceeds 127 characters, you have a definite 
problem because everything past the first 127 characters is ignored. 

The preceding example, which runs to 165 characters, excluding the PATH 
portion of the statement includes only those directory specifications that various 
installation utilities have added, or have requested be added to the AutoExec.BAT 
file. This does not, however, include working directories actually in use. 

Also, aside from exceeding the character limit, an excessively long PATH 
specification, can, itself, sometimes result in an undesirably slow search over too 
many directories or in conflicts over unexpected duplicate filenames. 

Thus, even if DOS permitted indefinitely long PATH specifications, they would 
not be particularly desirable. So, what’s the alternative? 

One option is to have the PATH specification only include those directories that 
are actually needed at any given time. While you are using Turbo Pascal, for 
example, the desired path specification might be C:\;C:\MOUSE; C:\TP;C:\TP\ 
UTILS;C:\TPROF;C:\TD;. 

This includes the root directory (C:\), the mouse directory (C:\ MOUSE), the 
two Turbo Pascal directories suggested by the Install program, the Turbo Profiler 
directory (C:\TPROF) and the Turbo Debugger directory (C:\TD). Note: TPROF 
and TD are not included with Turbo Pascal Standard Edition. 

At the same time, the default path set by your AutoExec.BAT file might be 
C:\QEMM;;C:\DOS;C: \HOT;C: \MOUSE;C:\ XBAT:D:\ FB;D:\WW;. 

Of course, you can change the PATH specification anytime. Simply type the 
new specification at the DOS prompt. For example: 


PATH Ci\;Ci\TD;CZ\TP;C:\TP\UTILS;C:\TPROF; | 


But remember, entering a new specification cancels the old PATH setting. To 
find out what the current path settings are, just type: 


PATH | 


The present path specification will be displayed but not affected. 

Although it is useful to know how to change the PATH specification, if you had 
to type one of these specification strings every time you called the compiler or exited 
to DOS, you would soon be pretty irritated. After all, what’s the point of using a 
computer if you can’t let the computer do the work? 

Suppose you want to set one path specification when you call the Pascal 
compiler, another when you call the C compiler, a third for Paradox and so on. And 
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suppose you want to restore a default specification when you exit each of these. 
The simple solution is to have batch files (,BAT) set up for each application. 

To call Turbo Pascal, for example, the TURBO.BAT file might contain: 
REM Turbo Pascal Entry BAT (TURBO.BAT) 


@ECHO OFF { no echo to screen } 
PATH CoN TPse ev TPs Cs\TP\VUELES; CENT RPROF:: { set new path spec } 


Cs { select the drive } 
CD\TP { ge lect @eirectory 2s 
TURBO € gcatl: Turbo Pascal > 
CD03 C-setlect:. rect dtr } 
CALL DOSPATH {-pestore orig .path. 2 


The DosPath.BAT file contains the original, system PATH specification as: 


REM DOSPATH.BAT 

REM sets default path specifications 

PATHCS \ECiNQEMM SC: \DOSsCE\NHOTSCE\MOUSE;C:\XBAT;D:\FB;D: \WW; 
Now, since the PATH specification is in the DosPath batch file, it is not included 

in the AutoExec.BAT file. Instead, AutoExec also calls DosPath, thus: 


@ECHO OFF 


CALL DOSPATH (-pepteaces: PATH Ce \e62\008 i 055.2 


Note: The CALL command allows one batch file to call another batch file 
without terminating. 

This way, when you do want to change your default PATH command, you only 
have to change it in one place. 

And when an installation program decides to enter a new directory specifica- 
tion in the PATH command, it simply appears as a normal PATH D:\PathName 
entry added to the AutoExec.BAT file. Afterwards, you are free to decide where 
you would prefer to have this appear: in the DosPath.BAT file or in a new .BAT 
utility to call the new program. 


Most important, your PATH specification does not suffer from terminal over- 
load. 


Chapter 2 


Using the Integrated 
Development Environment 


Turbo Pascal's Integrated Development Environment (IDE) is much more than just 
a compiler language. You could think of the IDE as the programmer’s equivalent 
of a well equipped garage/workshop, complete with neatly racked tools, work- 
bench, manuals, test equipment, a comprehensive stock room and even a test track 
to take your creation for a spin. 

But in programmer’s terms, the garage and workshop are a programming 
desktop with an interactive editor /compiler, while test equipment and manuals 
are supplied by the integrated debugger and the pop-up help features. The stock 
room, in the form of library units, has virtually everything needed to build any type 
of program. And the test track, of course, is simply the same computer you are 
presently using for program development, but with one difference: You don’t have 
to leave Turbo Pascal before you can try the program. 

And there’s more. 

First, programmers are human and make mistakes. Frequently, these are simply 
typographical errors—misspellings or omitted punctuation. Instead of making you 
search for such simple errors, Turbo Pascal will tell you about each error and show 
you where the error is, allowing an immediate fix. 

Second, Turbo Pascal allows you to use the mouse for a variety of workshop 
applications, making many operations faster and more convenient than keyboard 


is 
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commands. But the mouse is optional; everything works even if you do not have a 
mouse or do not want to use the mouse. It’s your choice. 

Third, Turbo Pascal supports multiple windows, allowing you to have two, 
three or more program source codes displayed, and allowing you to switch win- 
dows or cut and paste between windows conveniently. 

Fourth and most important, everything works together. This is not a collection 
of mismatched tools and parts where the biggest problem is finding the right 
wrench to match a nut. You do not need to spend hours trying to find the right set 
of commands to make the program match your video monitor or to make the mouse 
match the program, or figure out how to call a utility program without losing your 
present work. It’s all here, in one package, and it all works together. And it does so 
immediately. 

But this does not mean that you are restricted to a single layout. Turbo Pascal 
is extensively user-configurable; and all options can be either saved permanently 
or used temporarily, as you desire. 

For example, suppose you are using two different computers, one with VGA 
and a color monitor, and the other a portable with an LCD display. With VGA color, 
you would probably prefer a full color editor, but on the LCD display, colors may 
be to hard to distinguish so you might prefer to select either a different set of colors 
or a preset configuration optimized for LCD. Turbo Pascal gives you the choice. 


Configuring the Turbo Pascal IDE 


While Turbo’s IDE has changed through successive versions, most of the features 
of the IDE have either remained relatively constant or have evolved in a consistent, 
and usually self-explanatory manner. Thus, if you are thoroughly familiar with 
previous versions of Turbo Pascal, you may feel inclined to skip this chapter. You 
might, however, want to stick around for a quick tour through the current config- 
uration options. 

For those who are new to Turbo Pascal, or who have not upgraded since version 
3.0 (since there are still a few dedicated traditionalists around), this discussion 
begins with an introduction to the Integrated Development Environment and the 
principal configuration options. It assumes, however, that you are using a system 
with a hard disk, have installed Turbo Pascal 6.0 using the default directory settings 
in the Install utility and have included the statement ‘’d:\ TP;d:\TP\UTILS” in the 
PATH statement in your AUTOEXEC.BAT file or in the TURBO.BAT file suggested 
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in Chapter 1. If your configuration differs from this, you may need to adapt some 
of the following comments to your own circumstances. 

With Turbo Pascal 6.0 installed, you can call the IDE simply by typing 
C:\>TURBO at the system prompt. This produces an opening display similar to 
Figure 2-1. 


Figure 2-1: The Integrated Development Environment Main Screen 
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a aon t information 


Turbo’s IDE operates in text mode and reserves two lines of the screen—one at 
the top and one at the bottom—for a menu bar and prompt line. The remaining 
display lines (23, 41 or 48, depending on your display mode) provide a window for 
your application source code. But, before you load or create your first program, 
there are a few options you should be aware of. 

The menu bar, at the top of the screen, offers 10 primary pull-down menus, 
which can be selected in several fashions. First, any menu can be selected by clicking 
on the menu title with the mouse. 

But, since the mouse is not always convenient, or you may not have a mouse 
on your system, pressing the F10 key immediately highlights the File menu title. 
Then you can use the left and right arrow keys to select the desired menu from the 
menu bar, or press the hot key letter—highlighted—for the desired menu. 
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Your third option for calling menus is to use the Alt-key selections, again shown 
by the highlighted letter for each menu title. 

When a menu is selected—as shown in Figure 2-1—the first item on the menu 
is initially highlighted, but you can use the up and down arrow keys to shift the 
highlight to the desired item and then activate that item by pressing ENTER. 
Alternatively, you can press the highlighted hot key to select any item immediately 
or use the mouse to click on an item. 

In many cases, function keys are also shown for commonly required menu 
selections, such as F2 for File/Save or F9 for Compile/ Make or the F1, CTRL-F1, 
SHIFT-F1 and ALT-F1 keys for different Help features. All of these can be used at 
any time without the associated menus being selected or active. 

In Figure 2-1, the = (System) menu is shown together with the About menu 
item and dialog box. (Like many of the illustrations in this book, this figure is a 
screen composite. When the dialog box actually appears, the menu display will 
have vanished.) The About dialog box shows a single control button, OK, which 
can be selected by clicking the mouse, pressing ALT-K, or, since the button is already 
highlighted, by pressing the ENTER key. 

Last, the prompt line at the bottom of the screen—referring in Figure 2-1 to the 
menu, not the dialog box—offers additional information about the current selection 
or current dialog. You might also notice, however, that the Fl Help reminder 
appears on most prompt lines. 


Configuration Options 


The menu bar entries provide access to a series of pull-down menus, each offering 
a selection of features or tools for different uses. However, there would be little 
point at this time in explaining all of the features, for example, of the Debug menu 
before you've learned how to write a program that needs debugging. 

Therefore, rather than taking a detailed tour of all of the menu bar entries, we'll 
leave these for later when each is relevant to the topic at hand. 

Before you jump into writing programs, a few configuration options do need 
to be set now rather than later. The following sections contain recommendations 
rather than directives, and you may well have reasons for preferring a different 
configuration. In general, however, the options suggested here are intended to 
make programming more convenient. So, if you are not an experienced program- 
mer, they are strongly recommended. After all, you can change later to a new 
configuration if necessary. 
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Compiler Option Settings 


Select the Options menu, and then select the Compiler item. This calls the dialog 
box shown in Figure 2-2. Many of the settings shown are defaults set by the Install 
utility. 

In the Compiler Options dialog box, all of the options are shown within brackets 
[ ] (checkboxes0) indicating that more than one option in each group can be active. 
In other instances, parentheses () (radiobuttons) indicate that only one item in each 
group can be selected at any time. 


Figure 2-2: Compiler Options 

















Options 





——— == Compiler Options 





Compiler... 
emory sizes... 
inker... 

De ugger... 

irectories... 


ave options ... 
etrieve options... 


Code generation 
{[ 1 Force far calls [X] Word align data 





[ }] OQverlaus allowed [ ] 286 instructions 


Runtime errors Syntax options 
[ 1] Range checking | ([X] Strict var-strings 
{X] Stack checking [ ] Camplete boolean eval 
[X] I/40 checking { ] Extended syntax 









Debugg ing : 
[X] Debug information 
[X] Local symbols 


Numeric processing 
{ 1 8887/88287 





[X] Emulation 


onditional def ines 











In this case, the default selections are recommended. You may want to activate 
two additional selections, however, depending on the configuration of your system 
and of the systems on which your application will run. 

In the Code generation options, the 286 instructions option instructs the com- 
piler to use optimum instructions for 80286 (or 80386/80486) CPUs, but these are 
not compatible with 8086 CPU systems. If you are using an 80286 or later CPU but 
intend to run the application on 8086 systems, you may prefer to select this option 
during development (for advantages in speed and size) and then deselect it for 8086 
compatibility before the final compilation. 

In the Numeric processing options, the 8087/80287 option offers coprocessor 
support. This includes the 80387 math coprocessor or the 80486 CPU (which has an 
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integrated coprocessor). By default, Emulation is selected here, allowing the pro- 
gram to detect the presence of a coprocessor and operate accordingly, but only when 
the 8087 /80287 option is also selected. 

In the Runtime errors options, the Range checking option is occasionally useful. 
It can also, however, cause compiler errors by imposing too strict range checking 
when certain otherwise valid programming shortcuts are used. To avoid this 
problem, use the $R compiler directive for selective range checking rather than 
choosing global range checking from the options dialog box. 

The Syntax options are primarily a matter of personal choice, but the default 
selections are recommended. 

Under Debugging options, both the Debug information and Local symbols 
options are useful, unless you need to save every byte of space in the compiled .EXE 
program. Neither of these affects execution speed, and they are invaluable during 
debugging or profiling. If space is a consideration, deselect these options for the 
final compilation after your program is completely debugged. 

Last, the Conditional defines input box allows you to enter for symbol defini- 
tions to be used by conditional compilation directives. The details of this feature, 
which are of concern primarily to experienced programmers in special circum- 
stances, can be found in Borland’s Turbo Pascal Programmer's Guide. 


Selecting Options 


In the Compiler Options dialog box, six option groups appear. On initial entry, the 
first item in the first group will be highlighted. You can make selections with the 
mouse or by pressing the highlighted hot keys for each item (each setting is a 
toggle). You can also use the arrow keys to move within a group or the Tab and 
SHIFT-TAB keys to move between groups and press the SPACEBAR to toggle your 
selection. The TAB and SHIFT-TAB keys will also highlight the three control buttons 
at the bottom of the screen; you can press the ENTER key to select a highlighted 
control. 


Memory Size and Linker Settings 


The Memory size options (call as Options/Memory sizes) include settings for the 
stack size and heap limits, which can also be set using the $M compiler directive. 
Details on setting these values can be found in the Turbo Pascal Programmer's Guide. 

The Linker dialog box offers options for setting Map File generation (default is 
Off) and the Link buffer location (default is Memory). In this dialog box, the 
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selection buttons appear as parentheses ( ), identifying these as radio buttons and 
indicating that only one selection can be active in each list. 

Selecting Disk for the Link buffer location does free additional memory for 
compiling large programs but also slows compilation. You can also select this using 
the /L command line directive with the TPC compiler. 


Debugger Option Settings 


The Debugger options menu, shown in Figure 2-3, provides options for enabling 
symbol information for use by the Integrated and/or Standalone debuggers. Both 
can be turned off to reduce the size of your .EXE file for final compilation, but should 
otherwise be selected to ensure that debugging and profiling operations can be 
carried out. Integrated debugging is set by default, but you will probably find that 
the Standalone option is also useful with either the Turbo Debugger or Turbo 
Profiler. 


Figure 2-3: Debugger and Directory Options 
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The Display swapping options are selected by radio button, which means that 
only one mode can be active. The default Smart option is recommended. 


20 USING TURBO PASCAL 6.0 














Directory Options 


The Directories dialog box allows you to specify drive and directory paths where 
the compiler will search for source, include and .OBJ files, and where output .EXE 
and .TPU files will be written. 

The first input box, EXE & TPU directory, accepts only one drive/directory 
specification. If this entry is blank, output is made to the same directory where the 
source or Make file is found. Any .MAP files generated will also be logged to this 
directory. 

The Include directories input box will accept multiple path specifications, 
delimited by semicolons. White space is allowed before or after semicolons, but is 
not required. 

Both relative and absolute pathnames are permitted and may include paths 
relative to logged directories on drives other than the current (default) drive. 
Absolute pathnames are recommended, however, to avoid potential confusion. 
Complete specifications may be up to 127 characters long. 

The Unit directories input box specifies the directories where Turbo Pascal units 
(.TPU files) will be found, and shows the default path assignments provided by the 
Install utility. In the example shown in Figure 2-3, since the path specification is too 
long for the input box, an arrow symbol appears at the right. The display will scroll, 
either to show the balance of the string or to permit additional entry. The complete 
default path provided by the Install utility is: 


C:\TPs CE\TP\TVISION;: Ce\TP\BGL; CoATP\TURGOS; 

The Object directory input box specifies directories where .OBJ (assembly 
language) files should be found. 
Environment Options 


The Options/ Environment selection calls a menu of IDE-wide selections to config- 
ure your personal preferences for display, editor options, mouse operation and 
colors. These affect IDE operations only and have no affect on source code or 
compiled programs. 


Preferences 


The Preferences dialog box, shown in Figure 2-4, provides selections for 25-, 43- or 
50-line screen sizes (depending on your video adapter). By default, 25-line by 
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80-column text mode is selected, but you can select 43x80 displays for EGA video 
systems or 50x80 displays for VGA video systems. 

The Source tracking option determines whether the IDE opens a new window 
when you are stepping through source code or locating an error, and a file is 
encountered that is not already loaded. If you select Current window for this 
setting, the contents of the topmost Edit window will be replaced with the new file 
display. New window is the recommended setting. 

The Auto Save options are the most useful of the features in the Preferences 
dialog box. They offer automatic saves for Editor Files, Environment and the IDE 
Desktop settings. 

The Editor Files option automatically saves any source files that have been 
modified in the Edit window when any Run or Debug command is selected, or 
when the Files/DOS Shell command is selected. 

The Environment option ensures that all settings made during a session are 
automatically saved in the TURBO.TP configuration file before you exit from Turbo 
Pascal. 


Figure 2-4: Environment Preferences 
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The Desktop option operates in conjunction with the selections in the Desktop 
file group, causing desktop information to be saved at the end of a programming 
session in the TURBO.DSK file. The desktop configuration file saves the current 
edit window information, the positions of all windows on the desktop, history lists, 
breakpoint information, and so on. This allows you to end a programming session 
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and then later pick up at the same point where you left off. Use of the Desktop Save 
option is highly recommended. 

If you select None from the Desktop file options, no Desktop information is 
saved while the Current Directory or Config File Directory options determine 
where TURBO.DSK will be created. 

The Current Directory option allows several different TURBO.DSK files to be 
created in different directories and will be used when Turbo is called from the 
appropriate directory. 

The Config File Directory option saves TURBO.DSK to the same directory 
where TURBO.TP is found. This is generally the preferred choice. 


Editor Options 


The Editor dialog box offers a series of check boxes controlling the operation of the 
Turbo Editor. Each of these is essentially self-explanatory, but the following list 
explains them briefly. Default settings are shown with checks. 


«= [X] Create backup files—on save, renames existing source code file with 
.BAK extension. 

= [X] Insert mode—initializes Editor in insert mode. Regardless of initial 
setting, the Ins key toggles between insert and overwrite in any edit win- 
dow. 

«= [X] Autoindent mode—on new lines, automatically positions the cursor 
below the first non-blank character on the preceding line. 

» [ | Use tab character—when ON, inserts a tab character (09h) when the 
tab key is pressed, when OFF, tab entries are replaced by spaces as deter- 
mined by the Tab size setting. 

= [ | Optimal fill—when ON, leading spaces are replaced by tab charac- 
ters, reducing the size of the source code file. 

« [X] Backspace unindents—when set and the cursor is on a blank line or 
on the first non-blank character of a line, the Backspace key unindents 
the line to the previous indentation level. 

= [ |] Cursor through tabs—when set, allows cursor keys to move through 
tabs as if they were spaces rather than jumping through the tab positions. 

= Tab size—allows setting tab sizes within the range 2-16. Default setting 
is 8. 
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Mouse Options 


The Mouse options dialog box permits you to set the action initiated by the right 
mouse button, adjust the mouse double-click speed and, if desired, reverse the 
mouse buttons (for left-handed operation). 

The action initiated by the right mouse button operation provides a short-cut 
version of a menu item. Options are: 


» Nothing—no action 

« Topic search—equivalent to Help/Topic search (default) 
«= Go to cursor—equivalent to Run/Go to cursor 

« Breakpoint—equivalent to Debug/Toggle breakpoint 

» Evaluate—equivalent to Debug/Evaluate 

» Add watch—equivalent to Debug/Watches/Add watch 


The Mouse Double Click box provides a slider bar to adjust the speed with 
which a double-click event is recognized. Moving the thumbpad toward Fast 
shortens the maximum interval recognized as a double-click event; Slow lengthens 
this interval. Curiously enough, you can also use the right and left arrow keys to 
adjust the response speed. 

The Reverse Mouse Buttons check box reverses the right and left mouse 
buttons. Any change in setting does not take effect until the OK button is clicked. 


Startup Options 


The Startup Options provide settings to initialize operation of the IDE. Any changes 
you make in this option list are written directly to TURBO.EXE and do not take 
effect until the next time you load TURBO. These options are: 


« [ ] Dual monitor support—permits displaying the IDE on one monitor 
and the application output on a second monitor, if the appropriate hard- 
ware is detected. You can use the DOS MODE command to switch 
between the two monitors; the Turbo IDE will appear on the inactive 
monitor and the application output on the active monitor. You may also 
use the /D command line switch. 


Observe two cautions when using dual monitor support: 


Do not attempt to change the active monitor through the DOS 
shell (File/ DOS). 
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Programs that access the inactive video directly are not sup- 
ported. Results are unpredictable both during execution and 
debugging. 

» [ ] Graphics screen save—instructs the IDE to reserve an additional 8K 
buffer (in EMS if available) to enable a full graphics screen save while 
you are debugging graphics programs on EGA, VGA or MCGA systems. 
You may also use the /G command line switch. 

» [| ]EGA/VGA palette save—controls palette swapping on EGA/VGA 
systems. For use with applications that modify the palette registers, caus- 
ing palettes to be swapped whenever the screen is swapped. You may 
also use the /P command line switch. 

= [X] CGA snow checking—enable for slow CGA video; for fast CGA and 
for all EGA/VGA video, disable for faster video I/O. You may also use 
the /N command line switch. 

«= [ ]LCD color set—selects color set for LCD (monochrome) displays. 
LCD, VGA or EGA screens with gray-scale may operate in color modes. 
You may also use the /L command line switch. 

«= [X] Use expanded memory—permits the IDE to place overlaid code, edi- 
tor data and system resources in EMS. You may also use the /X- com- 
mand line switch to disable EMS. 

«= [X] Load TURBO.TPL—instructs the IDE to load TURBO.TPL on startup. 
If TURBO.TPL is not loaded, the SYSTEM.TPU will be needed to compile 
or debug programs, but SYSTEM.TPU must be extracted from 
TURBO.TPL using TPUMOVER. (See UTILS.DOC for details.) You may 
also use the /T command line switch. 


The Window heap size input box permits changing the default 32K setting. The 
valid range is 24K-64K, but a smaller heap size makes more space available for 
applications while reducing the number of windows that can be opened. You may 
also use the /W command line switch. 

The Editor heap size input box permits changing the default 28K setting. The 
valid range is 28K-128K. You should only increase editor heap size if you are using 
a slow disk drive for a swap file. If EMS is being used or the swap file is directed 
to RAM disk, do not change the default setting. You may also use the /E command 
line switch. 

The Overlay heap size input box adjusts the IDE overlay heap size. Default size 
is 112K, with a valid range of 64K-256K. If EMS is present, you may decrease heap 
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size—to free memory for compiling and debugging—without degrading perfor- 
mance. You may also use the /O command line switch. 

The Swap file directory input box is used to provide a drive/ path specification 
for a ‘fast’ swap area such as a RAM disk. If no swap area is specified, a swap file 
will be created in the current directory. You may also use the /S command line 
switch, followed by the drive/ path specification. 


Colors Options 


The Colors dialog box provides a means to customize the IDE display. Display 
elements are listed by Group and Item, and both foreground and background 
colors can be set for each element. Changes do not take effect until the dialog box 
is closed. 


The Save and Retrieve Options 


The Save Options and Retrieve Options commands call a dialog box, shown in 
Figure 2-5, allowing you to select a drive/path specification where the TURBO.TP 
and TURBO.DSK files will be saved or retrieved. 

The .TP file contains all options and editor commands, including settings made 
in the Find and Replace dialog boxes (Search menu), the Destination and Primary 
File options (Compile menu) and all settings made under the Options menu. 
History lists, desktop and breakpoint locations are stored in the .DSK file. 


Figure 2-5; Save Options 
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You can save differing versions of both the options and editor commands and 
the desktop settings in different directories for different applications or projects. 

If these files are not found in the specified directory, the TURBO.EXE directory 
will be searched. 

If Desktop is not None, Retrieve Options also loads the TURBO.DSK file; 
otherwise, only the TURBO.TP file is loaded. 


The Help Feature 


The Turbo Pascal IDE supplies several help features, beginning with the Help 
menu. You can open the Help window by pressing F1 at any time. 

Second, from an active Edit window, press CTRL-F1 to get language help for 
the procedure, function or term indicated by the text cursor (not the mouse cursor). 

Last, you can click on the Help button whenever it appears on the status line 
or in a dialog box. To close the Help window, press ESC, click on the Close button 
or choose Window/ Close. If you prefer, the Help window can remain on the screen 
while you operate within an Edit window. 

Help screens also contain keywords (highlighted) which you can select to call 
additional help information on that topic. Press the Tab key to move to the desired 
keyword, and then press ENTER or double-click on the keyword with the mouse. 

You can select any word on the screen by positioning the cursor and pressing 
CTRL-F1. If no match is found, a search is executed in the Index for the closest 
match. 

Text from Help windows can be copied and pasted into an Edit window (see 
Turbo Editor for instructions). You can also copy preselected program examples 
using the Edit/Copy Example command. To get help on Help, press F1 when the 
Help window is active. 


The Help Index 


The Help/Index command opens a dialog box displaying a complete list of 
keywords. You can scroll through them or do a quick search by keyboard entry. For 
a quick search using the entry ‘‘writeln” as an example, type w ri. Typing ‘w’ moves 
the display to the first keyword beginning with ‘w’, ‘r’ finds an entry beginning 
‘wr’, adding ‘i’ selects the first entry beginning ‘wri’, and so on. 

After selecting a keyword, either press ENTER or double-click on the entry to 
display the help text for this topic. 


The Turbo Editor 
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At the heart of the Turbo Pascal IDE is a powerful editor providing the facilities 
required to create Pascal source code. The editor responds to keyboard, mouse and 
menu commands. It features commands to insert, copy and delete text as well as 
execute search and replace operations. It also allows you to copy from Help 
examples, to and from a Clipboard window or between different program win- 


dows. 


The Turbo Editor commands are summarized in Table 2-1. Your best avenue to 
familiarity with the Editor, however, is simply to practice entering and revising 
program code. You will begin doing just that in Chapter 3. 


Table 2-1: Turbo Editor Commands 





Operation 


Cursor Movement Commands 


character left 

word left 

line up 

scroll up 

page up 

first of line 

top of window 

top of file 

first of block 

last cursor position 


Insert and Delete Commands 


insert mode on/off 
delete char left 
delete word right 
insert line 


Block Commands 
mark block 
unindent block 
write block to disk 
mark single word 
copy block 

cut block 

paste block 





Command Operation Command 
— character right —_ 

CTRL word right CTRL 

‘i line down L 

CTRL-W scroll down CTRL-Z 
PGUP page down PGDN 
HOME end of line END 
CTRL-HOME _ bottom of window CTRL-END 
CTRL-PGUP end of file CTRL-PGDN 
CTRL-O B end of block CTRL-O K 
CTRL-O P 

INS 

BACKSPACE delete char at cursor DEL 
CTRL-T delete to end of line CTRL-O Y 
CTRL-N delete line CTRL-Y 


SHIFT) SHIFTT SHIFT< SHIFT CTRL-K B CTRL-K K 


CTRL-K U 
CTRL-K W 
CTRL-K T 


CTRL-INS or Edit/Copy 
SHIFT-DEI or Edit/Cut 
SHIFT-INS or Edit/Paste 
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Table 2-1: Turbo Editor Commands (Continued) 


Operation 


Command Operation Command 


Block Commands (Continued) 


delete block 
hide/display block 
print block 

indent block 

read block from disk 


Search Commands 
search 

repeat last search 
search and replace 


CTRL-DEL or Edit /Clear 
CTRL-K H 

CTRL-KP or File /Print 
CTRL-K I 

CTRL-K R 


CTRL-O F or Search/ Find 
CTRL-L or Search/Search again 
CTRL-O A or Search/Replace 


Miscellaneous Editing Commands 


find place marker 
return to editor 

open file 

pair matching, backw. 
restore error message 
ctrl character prefix 
set place marker 

go to menu bar 

new file 

pair matching, forw. 
print file 

tab 

save file 

restore line 

quit IDE 


Mode Set Commands 
autoindent on/off 
optimal fill mode 

tab mode 

unindent mode 


CTRL-O N 

ESC 

File / Open 
CTRL-O | 

CTRL-O W 

CTRL-P (char) 
CTRL-K N 

F10 

File/ New 

CTRL-Q [ 

File/ Print 

TAB 

F2 or File/Save 
CTRL-Q L or Edit/Restore line 
ALT-X or File/Quit 


Options/Environments/Editor /Autoindent mode 
Options/Environment /Editor /Optimum fill 

Options / Environment / Editor / Use tab characters 
Options / Environment / Editor / Backspace unindents 


NOTE: Word delimiters are: space<>.;,(){}]%‘'+-*/$#_=1~?/°% & : @ \ and all con- 
trol and graphic (extended ASCII) characters. 


NOTE: The mouse can also be used for block marking operations in an Edit window by holding the 
left button down while dragging the mouse. 
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Search and Replace Operations 


The Turbo Editor provides a set of powerful search and search/replace operations. 
Selecting Search/Find or Search/Replace calls a menu dialog with an input 

box for entering the target string. Search strings may contain any characters, 

including control characters and line breaks (entered as CTRL-P CTRL-M). 

For Replace operations, a second input box is provided for entering the replace- 
ment string. 

When either the Search or Replace dialog menu is called, if the cursor in the 
active Edit window is positioned on a word or expression, that string will appear 
in the target string input box. 

If previous search replace operations have been carried out, you can press the 
down arrow, or click on the arrow at the right of the input box to display the 
previous entries for reselection. 

For replace operations, after choosing or entering the target string, tab to or 
click on the replacement string input box and then enter or select the desired 
replacement string. Search and replace options include: 


« [X] Case sensitive—distinguishes between upper and lower case charac- 
ters. 

= [ |] Whole words only—locates and/or replaces only whole words; i.e. 
words delimited on both sides by punctuation or space characters. 

«= | | Regular expression—recognizes GREP-like wildcards in the search 
string. 

= [X] Prompt on replace—calls a dialog box prompting for replacement for 
each match found. 

= Direction—choose Forward (default) or Backward search and/or replace 
when Origin is selected as From cursor. 

«= Scope—choose Global (default) or Selected text to limit search to high- 
lighted (marked) text. 

«= Origin—choose From cursor or Entire scope (default) for the search or 
search and replace origin. 


On Search and Replace, in addition to the OK, Cancel and Help buttons, a 
fourth button—Change all—executes global replacement. You may cancel Search 
and replace operations any time the search has paused by pressing ESC. 
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Pair Matching 


Since source files may be—and often are—riddled with parenthetical expressions, 
nested comments, range brackets and similar complexities, the Turbo Editor pro- 
vides a feature called ‘pair matching,” which locates matches for (parentheses), 
[braces], {braces}, and ‘single’ and “double” quotes. 

For an example of pair matching, position the cursor on an opening parenthesis, 
(and CTRL-Q [ to search for the matching closing parenthesis, ). Since parentheses, 
braces and brackets all occur in opening and closing pairs made up of distinct 
characters, the CTRL-Q [ (match forward) and the CTRL-Q | (match backward) 
commands automatically search in the appropriate direction, based on which item 
of the pair (open or close) the cursor is on. 

For single and double quotes, however, the opening and closing characters are 
one and the same. Therefore, the appropriate match forward or match backward 
command must be used. 

Also, since parentheses, brackets and braces are nestable—for example, (mul- 
tiple (levels (of (these) (delimiters) may be) nested)) within an expression—the 
editor tracks the level of the delimiters entered and exited during a search to find 
the appropriate match. In the case of unbalanced delimiters, the cursor remains at 
the original position. Otherwise, the cursor (and window) are moved to show the 
matching delimiter. 


Summary 


While the Turbo Integrated Development Environment provides a host of features 
beyond those discussed in this chapter, this introduction to setting up and using 
the Turbo Editor provides the basics for writing source code with Turbo Pascal. 

Many of the options settings for the IDE are assigned default values during 
installation, and others have been suggested here. Any of these can be changed as 
needed, however, and more than one version of the options settings can be saved 
in TURBO.TP files for different applications or circumstances. The Turbo Editor 
settings may also be revised as needed and are saved with the IDE option settings. 

Only your own experience in working with the Turbo IDE can make using the 
capabilities and features discussed in this introduction second nature. However, 
once you have worked with the IDE, its capabilities will quickly become second 
nature, leaving you free to concentrate on the real task of creating programs with 
Turbo Pascal, which will commence in Chapter 3. 


Chapter 3 


Creating a Pascal Program 


To many who are inexperienced with computers, the idea of creating a program is 
a mystical venture, a task reserved for those strange and esoteric individuals called 
programmers, hidden from the average, commonplace individuals of the world. 
However, this is simply a myth of ignorance; many people are programmers 
without being aware of the nature of their endeavors. 

For example, one of the most common computer applications is a spreadsheet, 
such as Lotus, MultiPlan, Quattro or SuperCalc. Using a spreadsheet is a form of 
programming, involving—even in its simplest forms—deciding how the sheet will 
be laid out, what formulas will be used and how calculations will be carried out. 

Granted, this is a very simple form of programming. Lots of safeguards are 
built into the spreadsheet to ensure at least minimal success, but it is still program- 
ming. The differences between simple spreadsheet programming and writing a 
program in Pascal are simply a matter of degree. 


Writing Source Code 


The first step in creating a program, regardless of the language used, is to decide 
what the program should accomplish. Once you have made this decision, the 
second step is to create the source code for the desired program. Source code consists 
of a file of instructions, which tell the computer language how to create the actual 
execution program. (The term code dates from the time when such source files were 
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almost impossible to “read” without complex deciphering. Happily, the term itself 
is no longer appropriate ... unless, of course, you write very bad source code.) 

In the case of a spreadsheet application, the source code is pretty much hidden. 
Only the instructions for a single cell can be viewed at any one time. Even so, they 
are still written in a form analogous to English and must be interpreted for use by 
the computer. In a spreadsheet as well as BASIC and other interpreted languages, 
the source code is executed by translating each instruction, as needed, into machine 
language. This translation is repeated each and every time a program instruction 
is needed. 

In Pascal, C, Ada, and other compiler languages the source code for a program 
is treated in a different fashion. In compiler languages, the source code instructions 
are translated only once into machine language and, afterward, only the machine 
language version is used for execution. The principal strength of this approach is 
efficiency, since the compiled code is usually smaller than a combination of source 
code and interpreter, and speed of execution, since the computer does not waste 
time repeatedly interpreting instructions. 

Turbo Pascal program source code is usually contained in a single file in ASCII 
format, allowing you to print it out as hard copy or edit it using either a word 
processor or—most often—the Turbo Editor. 

Other advantages to using a compiler language include being able to distribute 
executable programs while the source code remains proprietary (though not 
immune to reverse compilation or disassembly). These are secondary, however, and 
at the moment, the topic is source code. 


A Sample Program 


The best way to see what Pascal source code looks like is to create a simple program. 
The traditional beginning program, ‘Hello.PAS’, illustrates several basic elements: 


program Hello; 


begin 
writetnt “Hello,  worldl* 3: 
readln; 

end. 


These five lines of text provide the complete source code to compile and execute 
a program called HELLO.EXE. While the task accomplished is quite simple, the 
program demonstrates the initial structure of a Pascal program and employs the 
basic input and output capabilities that will be needed by most applications. 
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Entering a Program 


Before we go into how the HELLO program works, you should enter your own 
copy of the program using the Turbo Editor. 

If you are calling Turbo Pascal for the first time, or if you select Files / New, the 
IDE appears with a blank edit window, bearing the tithe NONAMEO00.PAS. The 
cursor is positioned at the upper left corner of the window, ready for your entry. 

Entering the Hello program with only five lines of text, shouldn’t be a difficult 
task. When you are finished, your program should look something like the screen 
shown in Figure 3-1. 


Figure 3-1: My_Name.PAS | 
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The Files Menu 


After you enter the program, the next step is to save the program file. In this case, 
since your program is yet unnamed, select Files/Save as to call the filename dialog 
box, which appears in Figure 3-2. 


Save as 


The filename dialog offers several options: First, you can either enter a 
drive/path/filename directly in the input box, select an existing filename from the 
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files list, or select a new subdirectory. You can also use some combination of these, 
such as selecting a filename from the list and then modifying it, or selecting a new 
directory and then entering a filename in the input box. 

You may click on the arrow icon at the right of the input box to get a history list 
containing drive/directory/filenames that have been used previously (if any). If 
you scroll to the end of the displayed list, you will find a parent directory specifi- 
cation, displayed as: ..\, which will take you to the parent of the current directory 
or to the root directory of the current drive. 


Figure 3-2: Saving a File 
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directory, or drive 


You may want to change drives. For this task, you need the Change dir option, 
which displays a directory tree, allowing you to select a new operating directory. 

Using Change dir is not precisely the same as selecting from a file list, because 
while the file list allows selection from different directories, it does not log the new 
directory as the current working directory. The Change dir option does. 

Finally, at the top of the directory tree is the choice Drives, which allows you to 
select a new disk drive. This can be any drive. 

Thus, between the Change dir..., Save, and Save as file options, you have the 
capacities for most of the file operations likely to be required in creating programs. 
For other operations, such as delete or rename, the DOS shell is provided. 


Open 
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The Open option is used to load an existing file. It calls a dialog box similar to the 
Save as files list, but with the addition of one new control button: Replace. 
The Replace button is an alternative to opening a new file window in the IDE. 
It replaces the file in the currently active file window with your new selection. 
Otherwise, clicking on the OK button after selecting a new file loads the selected 
file using a new Edit window. 


Other Options 


The remaining options on the Files menu are fairly self-explanatory, but are listed 
here in brief: 


New—opens a new edit window. 

Save (F2)—saves the contents of the current (active) Edit window under 
the existing filename (as shown at the top of the window). 

Save all—saves the contents of all open Edit windows using the existing 
filenames. 

Print—prints the contents of the active edit window, expanding tabs to 
spaces and sending the output to the DOS print handler. Ctrl-K P can 
also be used to print selected (highlighted) text only. 

Get info..—displays a dialog box with information about the file in the 
active Edit window and about conventional and EMS memory usage. 
This information-only display cannot be edited or changed. 

DOS shell—provides a temporary exit from Turbo Pascal, allowing exe- 
cution of DOS commands or programs. Available memory under the 
DOS shell is limited, so many programs may not be able to execute. To 
return to the IDE, type EXIT at the DOS prompt and press ENTER. 


In dual monitor mode, the DOS shell appears on the Turbo Pascal screen, not 
the application screen. 


Exit (Alt-X)—exits Turbo Pascal, returning control to DOS. If any file 
changes have been made but not saved, a prompt appears asking if the. 
files should be saved before exit. 
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Compiling a Program 


After entering and saving the example program, the next step is to compile the 
source code, finding out if you’ve made any mistakes in the process. Fortunately, 
mistakes are easy to correct in Turbo Pascal. 

Compiling under the IDE is simplicity itself. Either press ALT-F9, or select 
Compiler from the menu bar and then select Compile from the menu. Turbo Pascal 
will compile the source code in the active Edit window, unless and until an error is 
encountered. Correcting errors is one of the strengths of Turbo Pascal’s IDE. 

With conventional compilers, you write source code using the editor or word 
processor of your choice; then you invoke the compiler from the DOS command 
line with the name of the source code file. When errors are found, the error messages 
are written to the screen (or, optionally, to an error file) citing the source code line 
where the error was realized. Then, to correct these errors, you must return to the 
editor, search the file for the error location, correct the error, save the file, exit to 
DOS and, again, invoke the compiler. It is a tedious and tiring process. (In earlier 
times, when programs were written on punchcards, this type of compiling seemed 
like sheer convenience by comparison.) 

With Turbo Pascal, on the other hand, when an error is found, the editor 
window positions the cursor at the location where the error was realized and writes 
the error message on a banner across the window. You can see exactly what and 
where the error is and correct it immediately. Pressing ALT-F9 then restarts com- 
piling where it left off, until the next, if any, error is encountered. 

Thus, while conventional compilers usually generate a list of errors, Turbo 
Pascal stops compilation as soon as a single error is found. This is actually an 
advantage because, with an error list, a single actual error tends to result in a whole 
string of error messages, whereas with Turbo Pascal, each error can be corrected as 
soon as it is found. Furthermore, because the Turbo compiler is extremely fast, the 
overall result tends to be a very fast correction process. 

Also, when an error occurs in Turbo Pascal, if you’re not sure what the error 
message means, pressing the Fl (Help) key will call a help message relating to the 
error. Figure 3-3 shows an example where a single semicolon is missing from the 
source code, one of the most common errors of all. The small arrow above the Help 
display indicates the location where the missing semicolon should have been. 
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Figure 3-3: Compiler Help 
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And More Help 


While Help on error messages is useful, it is only a beginning. The Help feature is 
far more extensive than this, offering help on functions, procedures, operators and 
virtually every aspect of Turbo Pascal. 

To see an example, in the Edit window, position the cursor on the word writeln 
(use the arrow keys or click on the word using the mouse). Then press CTRL-F1. 
The result is the Help display shown in see Figure 3-4, telling you about the writeln 
procedure. 

Further, the bottom line in the Help window displays two additional high- 
lighted prompts: Write (text) and Write (typed). You can double-click on either item, 
or use the Tab key for selection and then press ENTER, and a new help display will 
appear with additional information on the selected topic. 

You can also scroll down the help window to find an example of how the current 
function or procedure is used. This example can be exported into the active edit 
window quite conveniently by calling the Edit menu and selecting Copy example, 
then positioning the cursor in the Edit window and pressing SHIFT-INS or calling 
Edit/Paste. If you want only part of an example, highlight your selection in the 
Help window (hold the left mouse button down while dragging the mouse, or use 
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the Shift-arrow keys), then select Edit/Copy or press CTRL-INS to copy the selected 
text, and paste in the edit window as before. 

Also, while the Help screen is displayed, notice the prompt line appearing at 
the bottom of the screen. It contains a reminder about the principal help features, 
all of which can be called by hot keys. 


Figure 3-4: Help on Routines 
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Help on Help 


Turbo Pascal’s Help system is quite extensive. In addition to complete pop-up help 
on error messages, functions and procedures, you are also offered a complete 
tutorial on how to use the Help feature itself. Figure 3-5 shows the Help Contents 
with four pages of topics. Things can’t get much more helpful than this. 


Additional Compiler Options 


Figure 3-6 shows the Compiler menu with the Compile option highlighted. For 
most programs, this may be all that is needed. For other circumstances, however, 
there are other compile options, including: 


« Make (F9)—invokes the built-in project manager to make an .EXE file. 
The project manager begins with the file named as Primary file, if any, or 
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else begins with the file in the active Edit window. The project manager 
will recompile all include, unit and/or interface files whose source files— 
if available—have been modified since last compilation. 

« Build—rebuilds all files involved regardless of their last compilation 
date. 

«= Destination—selects either Memory or Disk as the destination for the 
compiled .EXE file. When Memory is selected as the destination, the 
-EXE result is lost when editing is resumed. This is, however, faster than 
compiling to disk and is the preferred mode for most development. 


When Destination is set to Memory, any units recompiled during a Make or 
Build will be updated on disk. 

When Destination is set to Disk, an .EXE file is created using either the name 
of the file specified as the Primary file or, if none, the name of the file in the active 
Edit window. 


» Primary file—specifies which .PAS file will be compiled by the Make or 
Build options. This is used when working on programs that use several 
units or include files. To compile only the file in the active window, 
choose Compile. 


Figure 3-5: Help Contents _ 
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Executing a Program 


Once your source code compiles without errors, you are ready to run the program, 
which is even easier than compiling. Just press CTRL-F9, or call Run/Run to begin 
execution. If you have not compiled the program, or if you have made any changes 
to the source code since last compiling, Turbo will recompile and then execute. 
For our example program, this is all that’s required. In other circumstances, 
however, you can invoke additional options or they may be invoked by circum- 
stances. The complete Run menu is shown in Figure 3-6, and explained below: 


= Run (Ctrl-F9) 
parameters passed though the Run/Parameters option. If the source 





executes the current program using any command line 


code has been modified since the last compilation, the compiler’s inte- 
grated project manager will automatically make and link the program 
before execution. 


Figure 3-6: The Compile and Run Menus 
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If debugging is active (i.e., the debugging options are set and one or more 
breakpoints have been set), the program will execute until a breakpoint is reached. 
If the Step over or Trace into commands have been invoked, Run/Run will 
prompt you, asking if the program should be rebuilt. If the response is Yes, the 
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program manager will make and link the program before restarting execution from 
the beginning. (See also Program reset.) If the response is No, execution will resume 
at the present location, continuing until another breakpoint is encountered or the 
program ends. 

CTRL-BREAK will cause execution to stop on the next source line in the 
program. If the source code is not available, a second CTRL-BREAK will terminate 
execution, returning control to the IDE. 


«= Program reset—terminates the current debugging session, releasing any 
memory allocated by the application and closing any files opened by the 
program. 

«= Go to cursor—executes the program until reaching the cursor position in 
the active Edit window. If the indicated source code line does not contain 
an executable statement, a warning message is displayed. This command 
can be used to initiate a debug session. 


Go to cursor does not set a permanent breakpoint and does not prevent the 
program from halting at any breakpoint encountered prior to reaching the cursor 
position. When this happens, Go to cursor can be invoked again. 


= Trace into (F7)—executes the program statement by statement, tracing 
into any procedure or function calls for which the source code is avail- 
able. 

«= Step over (F8)—executes the program statement by statement, but does 
not trace into any procedures or functions called. 


Before either the Trace into or Step over commands can be invoked for tracing 
program execution, both Debug information (Options /Compiler) and Integrated 
(Options/ Debugger) must be selected. 


« Parameters—allows entry of command line parameters required by an 
application exactly as if they were entered from the DOS command line. 
DOS redirection commands will be ignored. 


Parameters take effect only when the program is started and cannot be changed 
during execution. If a change is required, select Program reset, then restart the 
program with the revised parameters. 
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Summary 


Thus far, you’ve seen how to write a simple program and how to compile and 
execute it. At the same time, you’ve seen how the IDE handles errors and have had 
a tour of the Help features available to assist you in correcting mistakes. 

Further, three of the menu bar options, File, Compile and Run, have been 
discussed in some detail though most of the features they offer are of only minimal 
use at this point. But they’re there when you do need them. And the Edit menu has 
been mentioned in passing. There will be more on this and other menu options later. 

Now that you know how to enter, compile and run a program, Chapter 4 will 
show you how programs are put together and help you begin writing programs 
with more interesting functions than sending a simple message to the screen. 


Chapter 4 


The Anatomy of a Program 


Thus far, the principal topic has been how to use Turbo Pascal’s Integrated Devel- 
opment Environment. There will be more to discuss about the IDE at later times, 
but now that you've learned the basics of using the compiler and the IDE, it’s time 
to turn to the construction—or the anatomy—of a program. 

In simplest possible form, a program consists of four parts: 


«= Header—program title 

«= Global declarations—constants, types, variables 
«= Subroutines—procedures and functions 

» Main routine 


The only part a program is absolutely required to have is the main routine. Few 
programs, though, are actually this skeletal, or if they are, they are very limited in 
scope and function. Even the program HELLO.PAS, introduced in Chapter 3, which 
did very little at all, included two of these parts: the header and the main routine. 


The Program Header 


The first program part, the header or program title, is rather like an appendix—the 
only time you’re really aware of it is when something goes wrong. This is because 
the compiler simply ignores the single word following the declaration program, 
except when an error occurs. 

In HELLO.PAS, the header appeared as: 
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program Hello; 


Simple as the header appears, it has limitations: the title following the reserved 
word program can only be one word, and the title word must be terminated by a 
semicolon. 

Other than creating this small potential for errors, the title does nothing but 
serve as an abbreviated reminder of what the source code is for. 

There are a number of other “one word” limitations in Pascal (and in other 
languages). Variables, constants, procedure and function titles and other identifiers 
are also limited to single words. We can get around this limitation, however, by 
using an underscore character to connect two words, making them one in Pascal’s 
terms. Thus, while the title Hello World would not be allowed, we can use the 
underscore character to change the two-word Hello World into Hello_World, a form 
which is easily read (by humans) but is still interpreted as a single word by Pascal. 

At the same time, however, this brief title tells us very little about the program 
and serves absolutely no other purpose, since even the name of the compiled .EXE 
program is determined by the filename of the source code file, not the program title. 
Therefore, in the future, this title line will be discarded in favor of a more informa- 
tive header ... as you will see subsequently. 


The Main Routine 


In some languages, such as C, the main program or main routine must actually be 
identified by a standard name. In Pascal, however, the main routine is identified 
only by the fact that it is the last block of code in the source listing. It does not bear 
a procedure or function title, though it does start with the reserved word begin and 
terminate with another reserved word, end. 

The simplest way to demonstrate the main routine is to show you another 
sample program: 


program My_Name; 


const 
Name = ‘Your Name Here'; 

begin 
writelLn( 'My name is ', Name ); 
readln; 


end. 
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Notice, particularly, that the end statement is terminated with a period. While 
this is somewhat redundant, the period is required at this point to indicate that this 
is the absolute end of the source code listing. 

The begin..end keywords are block delimiters—indicators setting off or group- 
ing blocks of instructions for various reasons. In this case, they enclose the main 
routine. Normally, this combination of keywords will appear regularly elsewhere 
in your code, but, except for this final end statement, all other end statements will 
either be terminated by a semicolon (;) or not be terminated at all. 

For the moment, assume that all end statements except the last will be termi- 
nated by a semicolon, while the last end statement will always be terminated by a 
period. Also, you will never have a begin statement without a corresponding end 
statement, though end statements can be paired with other initiating keywords. 

What appears between the begin..end delimiters is the main body or main 
routine for this program. If the program is going to do anything at all, there will be 
at least one program instruction in the main routine. 

Most programs use the main routine to call subroutines that contain the 
principal program instructions. In this example, the main routine is the program. 


Global Declarations 


The third program element, global declarations, may or may not appear in any given 
program. They may appear in several different forms, or even in more than one 
form in different places within a program. 

In the example program, My_Name, a single global declaration appears: 


const 
Name = 'Your Name Here'; 

The details of declarations, both global and local, and the various types of 
declarations will be discussed later. One characteristic you should note, however, 
is that multiple declarations may follow a single declaration header—const is the 
declaration header here—and that no begin..end delimiters are required to enclose 
these. 


Subroutines 


One of the big advantages of Pascal is the use of structured programming. This means 
that a program is divided into tasks, or subroutines, each of which accomplishes a 
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specific job but does so without interfering with, or interference from, other 
program elements. 

These program elements are known collectively as subroutines but, individu- 
ally, are called functions or procedures. A second example program—My_Name2.PAS— 
elaborates on the task handled by My_Name.PAS by using two subroutines (and a 
few other changes): 


{ssesescetseseseees Sess 2=22ss=='}) 
{ My _Name2.PAS } 
{ introduces procedures’7 } 
{ -end: ftunettions } 
{ssesssteeSeeSsseesseseseseze2=) 


Name : string; 
1 2 tHteger: 


function GetName: string; 


var 
Tenpotr: 5 8trings 
begin 
Cl teers 
writec: pat’ *s your name? ').3¢ 


readin <tempstr 22 
GetName := TempStr; 
end; 


procedure WriteName( WhatName: string; Step: integer ); 
begin 
gotoxyt. Step. * 4, Step #2 > 
write(€ ‘Hello, ', WhatName ) 
end; 


=e Ne 


begin 
Name := GetName; 
for 4 eee. to. 10 Ao 
WriteName( Name, i ); 
readln; 
end. 


In this example, two subroutines are created to handle specific tasks: the 
function GetName has the task of erasing the screen, writing a query, and reading 
a response, which is returned to the main procedure. The procedure WriteName is 
given the task of setting a screen position and writing its own message to the screen. 
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This division of labor is one of the advantages of structured programming: Each 
program area operates like a small, semi-independent program, accomplishing a 
specific task. When a subroutine is called, total control is passed to that subroutine 
until it is finished and returns control to the calling routine. For as long as a 
subroutine is active, it is independent of the rest of the program, though any 
subroutine may, in turn, call other subroutines. 

The example also demonstrates that there are two types of subroutine: func- 
tions and procedures. 

The distinction between a function and a procedure is quite simple. Both types 
of subroutine can accomplish complex tasks, both may be called with a parameter 
list (as WriteName is) but a function is a subroutine that always returns a value of 
some kind after its task is completed. A procedure does not return a value. 

In many respects, this distinction is arbitrary, but it is necessary for the compiler 
to understand how a program is structured. 

Both types of subroutine are explored further and their internal structures 
explained in detail a little later, but first we'll look at a few other program elements. 


Program Comments 


The first example program, My_Name.PAS, began with the declaration program 
followed by a single word program name. But, as mentioned, this didn’t really 
allow enough room to say much of anything about the program. Therefore, the 
second example, My_Name2.PAS, uses a different type of header: 


{ My _Name2.PAS } 
{ introducing procedures, } 
{ and functions 


In this fashion, virtually any amount of information can be included in the 
program header and may, if necessary, extend over several lines or even several 
pages. 

In Turbo Pascal, the brace characters, { and }, denote the beginning and ending 
of programmer comments; everything between the braces is ignored by the com- 
piler. Asecond set of character pairs, (* and *), can also be used for the same purpose. 
But unlike the braces which are specific to Turbo Pascal, the parenthesis /asterisk 
pair is also recognized by other versions of Pascal. 
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Alternating comment identifiers can be nested as (*...{...}...") or {...(%...")...} but 
each comment identifier must be matched with its corresponding delimiter. For 
example, { must be closed with } and (* must be closed with *). 

Comments can be inserted virtually anywhere within the program. Frequently, 
brief comments will be appended to program instructions as a reminder—for the 
programmer—of why a subroutine or a particular structure is being used. 

You can also use comment braces to disable a portion, or portions, of the code. 
You might, for example, want to test operation while some segment of code is 
disabled. Or you might want to disable a test routine or save other unneeded 
segment of code, but reserve it in case of future need. 

Comments cost nothing. Anything enclosed in comment braces is totally 
ignored by the compiler as though it were not there. 

Comment identifiers are used in one other circumstance: to indicate compiler 
directives, either opening identifier is immediately followed by a dollar sign ($). 
Examples of this usage will appear in later programs. 

Finally, paired comment indicators do not have to appear on each line. A single 
opening comment indicator may appear on one line with the matching, closing 
indicator appearing several lines or even pages later. Everything between the two 
comment delimiters will be ignored by the compiler. 


Units 


My_Name2.PAS also introduces the program element known as a unit—a library 
that contains the implementation code for functions or procedures that may be used 
by application programs. 

In early versions of Turbo Pascal, a single function library was sufficient to 
contain the code for all of the functions and procedures used. But as Turbo Pascal 
grew and provided more features, the library was split off into several separate 
libraries—using the extension .TPU—so that applications could use the uses state- 
ment to call only those libraries it required (for example, only those libraries 
containing the implementation code for the functions or procedures actually used 
by the application). 

In the first example, My_Name.PAS, only the writeln and readIn procedures 
were called, and no uses statement was required since both of these procedures are 
contained in the default library, TURBO.TPL, which is always available to the 
compiler. 
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In My_Name2.PAS, the ClrScr procedure is used, which requires the CRT unit 
for its implementation: 


uses Crt; 


Only one uses declaration can appear in a program, but it can be followed by 
multiple unit names, as in: 


uses Crt, Dos, Graph; 


As many units as needed can be called, and new units can be created, without 
penalty, because Turbo Pascal uses a smart linker, which does not include the entire 
unit in the compiled program, only the implementation for those procedures or 
functions that are actually used by the application. 

If you omit a unit declaration in the uses statement, the compiler will prompt 
you with the error message: unknown identifier, positioning the cursor on the 
unidentified procedure or function call. If you are unsure which unit is needed for 
the function or procedure—assuming that this is a standard Pascal subroutine— 
simply press CTRL-F1 to calla Help window for this subroutine. The Help window 
will identify the unit where the function or procedure is implemented. 

Why not simply use a header to call all available units and let the linker decide 
which are necessary? Well, it’s possible, but you would pay a penalty in compiler 
speed. The linker would have to sort through all 44 units supplied with Turbo Pascal 
6.0, which would require a large header and cause slow compilation. 


Indented Code 


Another element you should notice in our example programs is that program lines 
are indented in steps. This element is not required by Pascal but is provided entirely 
for the benefit of the programmer. It is a device to group program instructions 
visually, according to functional blocks. 

My_Name2.PAS could also be written as: 


uses Crt; var Name : string; 1 + integers function 

GetName: string; var TempStr : string; begin clrscr; 

write( 'What''s your name? ' ); readln(€ TempStr ); 

GetName := TempStr; end; procedure WriteName( WhatName: 
string; Step: integer ); begin gotoxy( Step * 4, Step + 2 ); 
write€ ‘Hello, ', WhatName ); end; begin Name := GetName; 
for i := 1 to 10 do WriteName( Name, i ); readln; end. 
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It would compile and function precisely the same as before. Reading the code, 
however, is considerably more difficult—for humans, at least. 

Thus, indentation is used, in three character steps, to provide visual alignment 
of separate routines within the program. In this fashion, matching begin and end 
statements will always be aligned, while the instructions grouped by these delim- 
iters will begin with a three space indentation. Interior groupings will be indented 
another three spaces, and so on. 

The preference for indented code is virtually universal, so much so that the 
Turbo Editor and most other sophisticated programming editors offer the option 
of automatically aligning the cursor with the beginning of the previous line, thus 
making stepped alignment convenient. 

Since Turbo Pascal does limit line length, to 127 characters including leading 
blanks, some programmers prefer to use a two-space indent step. A few even limit 
themselves to a single space, allowing space to write more compact source code 
with longer program lines. 

In this book, clarity is the primary concern rather than attempting to make 
source files as small as possible—remember, spaces and indentation in the source 
code have no effect on the size of the compiled .EXE program—so a step indentation 
of three spaces will be standard. 


The Naming of Names 


Pascal offers almost complete flexibility in assigning names to programs, subrou- 
tines, constants, types or variables, but there are some restrictions. 
First, Turbo Pascal uses the following subsets of the ASCII character set: 


= Letters—the standard English alphabet, consisting of the characters A..Z 
and a..z. 

«= Digits—the Arabic numerals 0..9. 

= Hex digits—the Arabic numerals 0..9 and the characters A..F or a..f. 

« Blanks—the space character (ASCII 32 / 20h) and all ASCII control char- 
acters (ASCII 0..31 / Oh..1Fh). This includes the end-of-line character 
commonly denoted as CR (ASCII 13 / ODh). 


In general, these are all the characters that can be typed directly from the 
standard keyboard, with the exception of the Del character (ASCII 7Fh), which most 
keyboards no longer supply directly. (This is not the same as the DEL key on the 
keypad or the Delete key on an extended keyboard.) 
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This is only about half of the complete ASCII character set, however. The 
extended ASCII character set (128..255 / 80h..FFh), also called the graphics charac- 
ter set, is not used or recognized in program statements. However, these characters 
can be, and often are, included in display (output) strings to create screen boxes, 
text scrollbars or other special symbols. 

Second, a number of ASCII characters are special symbols, including: 


eS £2 OP Se QS gf PF Pe eee Se OOD = £3 
At the same time, several character pairs are also special symbols: 
S= FS 28 os LF BP . «2 


Last, the space character (ASCII 20h) is, itself, a special symbol, called a 
delimiter, which separates program terms, just as it is used here to separate English 
words. In general, some form of delimiter—either a space character or a carriage 
return (line break)—is required to make program names identifiable. 

However, the other special symbols (preceding) can also act as delimiters and 
do not require additional spaces, though space characters may be used wherever 
desired simply for the programmer’s convenience. : 

The special characters listed above are not permitted in the names of programs, 
variables, constants, types or subroutines. This leaves only seven punctuation 
symbols that could be included in names: ! ~ & _ | \ ?. Since six of these are special 
symbols in other languages, however, only one, the underscore (_) character, is 
commonly employed. 

Thus, names can consist of the characters A..Z, a..z, 0..9 and the underscore. But 
remember two things: in Pascal, uppercase and lowercase—A and a—are the same, 
and names cannot begin with the characters 0..9, though numbers can appear 
within a name. 

Now if this sounds like a long list of restrictions, it is only because they are 
unfamiliar to you. The even greater list of restrictions in English, which are 
understood but unstated, are so familiar that you never consciously recognize them 
as restrictive. 

To recap: names or identifiers in Pascal are terms denoting constants, fields (in 
records), functions, objects, procedures, programs, records, types, units or vari- 
ables. Program identifiers can be any length—though only the first 63 characters 
will be significant—but they must begin with either a letter or the underscore 
character. After the first character, they may contain any valid ASCII character, but 
may not include spaces or control (special) characters. Identifiers are not case-sen- 
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sitive; upper and lower case characters are treated equivalently. For example, 
My_Name is the same as MY_NAME or mY_nAmE, but is not the same as 
MyName. 


Reserved Words 


Finally, Pascal has a number of words that are reserved and cannot be used for any 
purpose other than their predefined meanings. The reserved word list consists of: 


and array asm begin case const 
constructor destructor div do downto _ else 
end file for function goto if 
implementation in inline interface label mod 
nil not object of or packed 
procedure program record repeat set shl 

shr string then to type uni 
until uses var while with xor 


Turbo Pascal also has a list of standard directives, which, unlike reserved words, 
may be redefined by the programmer, though this is not recommended: 


absolute assembler external far forward 
interrupt near private! virtual 
Choosing Identifiers 


Within the limits described above, Pascal follows Humpty Dumpty’s dictum: 
“When I use a word, it means just what | choose it to mean—neither more nor less.” 

In some languages, such as early forms of Basic, names for program elements 
were severely restricted. One of the hardest parts of creating a program was simply 
remembering that X1 was used for a list index while Y2 was a screen coordinate 
and A3 held the subtotal for the current sales record. 

With Pascal, a great deal of this uncertainty is relieved because you can select 
names that are self-identifying. For example, you might call the variable holding 
the list index List Index, while a screen coordinate could be YPos, and a sales 


1 private is a reserved word in object definitions 
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subtotal identified quite understandably as SubTotal. You might prefer even shorter 
terms, such as Lstldx and SubTot or TSub, or longer terms, such as 
Sales_Item_List_Index, Y_Axis_Position and Current Sale Subtotal. 

Generally, programmers choose labels long enough to be distinct reminders of 
their function but short enough not to bea total encumbrance when typing program 
source code. Within these considerations, there are three factors to remember: 


« a Pascal program line cannot exceed 127 characters 

« only the first 63 characters in an identifier are significant 

« the length of the identifiers used in the source code do not affect size of 
the compiled program 


As a rule of thumb, choose labels—names or identifiers—that suit your conve- 
nience and mnemonic requirements, the compiler will translate them to suit its 
convenience and mnemonic requirements. 

Thus, you have the best of both worlds. 


A Rose By Any Other Name 


One problem which bothers many novice programmers is the matter of names 
because a variable may have one name in one procedure then, when passed as a 
parameter to another procedure, receives an entirely different name. 

But the venerable William Shakespeare, even though he was programming 
actors rather than computers, caught the gist of the matter in his much quoted line 
“What's in a name? That which we call a rose by any other name would smell as sweet.” 

In programming, names are not important and may change as often and as 
widely as we choose without affecting the element which they refer to. For example, 
here in the United States my name is Ben, but in Thailand I’m commonly called 
‘Adjaun,’ and in Sri Lanka I’m addressed as ‘Professor’. And when I visit my 
grandmother (and sometimes my mother), I also answer to ‘Butch’ ... and to other 
names in other places ... but I’m still the same person regardless of the name. 

Thus, when I create a procedure with a local variable titled BlackBox, I can pass 
BlackBox to other procedures where this element is known as Container, Volume 
or even Thing without changing the nature—or the contents—of the variable. For 
example: 


procedure NewBoxC...); 
var 
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BlackBox: . BoxStruct; 


AddSolids( BlackBox ); 
Arrange( BlackBox ); 
if TestBox( BlackBox ) then 


procedure AddSolids( var Container: BoxStruc ); 
procedure Arrange( var Volume: BoxStruc ); 
function TextBox( Thing: BoxStruc ): boolean; 


And each of these subprocedures is working with the same BlackBox even 
though each has a different name reflecting, to varying degrees, the nature of the 
local task—just as my own cognomen can vary in different countries and circum- 
stances. 

So, why not use the same name throughout? 

In some programs, this might be practical but not always because TestBox 
might also be called from another procedure where the local variable name was 
BlueBox or even BoxArray|i]. And, as long as the nature remains the same, the name 
is unimportant. Further, even if the name remains the same, these are simply two 
different variables which happen to have the same name ... but are not necessarily 
the same variable. 

Last, remember, when the program is compiled, these names will be forgotten 
anyway (except as temporary debug information for cross-referencing to the source 
code). 


Alias Smith and Jones: Passing Parameters by Address 


In the preceding example, two of the three subprocedures included the keyword 
var immediately before the variable declaration while the third, TestBox did not. 

Normally, when a variable is passed to a subprocedure, the variable is passed 
by value; meaning that the contents (value) of the variable are transferred but the 
receiving procedure has its own, local copy of the variable—as well as its own local 
name. And, when this happens, any operations on the local copy—the variable’s 
clone—are strictly local and do not affect the original variable. 

However, the keyword var indicates that a variable is being passed to a 
procedure by address and, even though the name may be different locally, this is 
the same variable. Any local operations—as in AddSolids and Arrange—are actu- 
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ally operations on the original variable BlackBox ... even though these operations 
are executed using a different, local name. 

So, why is this not the default? 

The principal reason is that most variables do not need to be passed by address 
and, in many cases, should not be. In general, most variables need to be passed as 
information for local use but are not expected to return a changed result to the 
calling procedure. 

In AddSolids and Arrange, the implication is that the original variable is 
expected to changed in some fashion and that these changes are needed by the 
calling procedure. But, in TestBox, the only information expected back is a 
True/False indicating whether the test has succeeded or failed. And, since this 
could involve testing by destruction, there is certainly every reason not to want the 
changed information returned. 

For a clearer example, a simple sort routine might be sorting a list of names by 
calling two subprocedures, thus: 


if SwapNames( NameCLiJ, NameCjJ] ) then 
OrderNames( NamelLild, NameCjJ] ); 


And the subprocedure SwapNames would receive the two variables as infor- 
mation, simply returning a True/False result to indicate whether the next step 
should be executed or not. 

But the subprocedure OrderNames would receive the same two variables by 
address, as variable parameters, so that it could swap the information at one 
address to the other address and vice versa. 

Notice, however, that both are called in exactly the same fashion and there is 
nothing in the procedure calls to indicate that one is receiving parameters as 
information and the other as addresses. Only examining the procedure declara- 
tions, themselves, will tell you this. 

And you will see both forms, in various mixtures, appearing in subsequent 
chapters and examples. 


Summary 


In this chapter, you’ve seen the basic structure of program source code: both the 
structural elements used by the Pascal compiler—the header, main routine, decla- 
rations and subroutines—and the structural elements used to benefit the program- 
mer—comments and stepped indentations. 
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You have also been introduced to the uses statement and the concept of 
units—libraries containing the implementations for Pascal's tools. 

The characters, special symbols and reserved words used by Pascal have been 
identified, together with a few comments on constructing your own symbolic 
labels. 

Finally, I’ve also discussed the importance—or unimportance—of names and, 
briefly, illustrated how variables can be passed either as information for local use 
or by address to return information to the calling procedure. 

But these are only the coarse structural elements of programming. Much more 
detailed elements are also necessary, such as identifiers, data types, declarations 
and assignments, which will be introduced in the next chapter. 


Chapter 5 


The Shapes of Data 


The essence of programming is the manipulation of data. This is true whether you 
are using a spreadsheet or a word processor, or playing a video game, or writing 
an application. As programmers, we make things easier for ourselves by defining 
data as types, which can be manipulated in specialized, convenient fashions. 

While custom data types can be defined to fill specialized purposes, Turbo 
Pascal provides a variety of predefined base data types suitable for most require- 
ments. These base data types can also serve as the basis for defining more special- 
ized types. 


Predefined Data Types 
The various predefined data types are categorized in six major classes: 


« Simple types—includes both integer and real numbers, boolean values 
(True/ False) and alphabetical characters. 

« String types—arrays of character values; used principally for text infor- 
mation. 

» Structured types—records mixing one or more simple and/or string 
types, where several associated pieces of data need to be handled as a 
collection rather than individually. 

» Pointer types—addresses (in memory) of other data types; provide 
access to data without having to pass the data itself between processes. 

« Procedural types—more commonly known as procedures or functions. 
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« Object types—a specialized type, which combines structured data types 
and procedural types. 


The last four data types—structured, pointer, procedural and object types—are 
covered in later chapters. This chapter covers only the simple and string data types. 


Simple Data Types 


Even simple data types break down into a number of subdivisions. The two 
primary divisions are the ordinal and real types. The differences between these two 
are not difficult to define. Ordinal data types are all data types with a finite number 
of elements; they have integer values and can be counted. Real data types consist 
of floating point or decimal numbers. They cannot be counted because between any 
two real numbers, there are always an infinite number of remaining elements. For 
example, between 1.05 and 1.06 an infinite number of other real numbers occur, 
including 1.051, 1.05101, 1.0510102 ... 1.0590102, and so on. Mathematically speak- 
ing, there are also an infinite number of elements between any two of these. Thus, 
real values cannot be enumerated, though this makes them no less useful. 


Ordinal Data Types Turbo Pascal provides seven predefined ordinal types: inte- 
ger, shortint, longint, byte, word, char and boolean.” Each has a specific size, format 
and valid range, as shown in Table 5-1. 


Table 5-1; Ordinal Types 





Base Type Type Id Valid Range Format 

integer shortint -128..127 8-bit, signed 
byte 0..255 8-bit,unsigned 
integer -32,768..32,767 16-bit, signed 
word 0..65,535 16-bit, unsigned 
longint -2,147,483,648..2,147,483,647 32-bit, signed 

character char 0::255 8-bit, unsigned 

boolean boolean 0..1 1-bit, unsigned? 


2 Some sources suggest that boolean should always be capitalized since the term is derived from 
George Boole, the mathematician who devised the rules for boolean operations. Many words, 
however, have entered our language beginning as individuals’ names but have long since lost 
their explicit association with the person whose name was used ... and, likewise, are no longer 
capitalized. And others, such as Pascal, remain exceptions. 

3 While boolean values store only one bit of information, a boolean variable is still created as a 
byte (8-bit) variable. 
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In addition to these seven base types, two other classes of ordinal types—enu- 
merated types and subrange types—are derived from the base types. 

In the simplest possible terms, ordinal types can be considered as subsets of the 
set of whole numbers, with each type limited to a specific range. But, as you may 
have noticed, two of the ordinal types, byte and char, are identical in format. Why 
have two different types? The simplest answer is that the two types are used for 
different purposes: byte is used for numbers while char is used for characters (by 
default, for the ASCII character set). 

Even though the types byte and char are identical in size and format—however, 
both are 8-bit, unsigned—instances of technically identical types are not completely 
interchangeable. The reason is that Pascal imposes strict rules that prevent variables 
of one data type from being accidentally used as another type. 

There are occasions, of course, when it’s useful to be able to change one data 
type to another, a process knownas typecasting. In some cases, among ordinal types, 
typecasting is automatic, accomplished by simply assigning an instance of one type 
to an instance of another type. This, however, can be dangerous when the two types 
are not completely compatible, as is demonstrated by the following brief test 
program, INT_TEST.PAS: 


{ INT_TEST.PAS } 
{ demonstrates typecasting } 


{ errors with integers } 
(ssseseseesessssssseeses=assaz} 
uses Crt; { seeeseces=e OUTPUT =ssee= 
var { int sint | int 
a, c : integer; £ “42545 0 | 0 
Bb,» Gg ¢ BHOrTETNt? { 423453 i ae 125 
begin {sssssSesesestestecateesesss= 
clrser: 
writeltn¢ ° int. siAant- 4 Ltt. See? IF 
a := 12345; b fs .-0 
¢ r= Gs Gg. 8s Tes} 
writelnt asé, Be6G, “ 1°", x65. 2836 22 
db <= 6; c := d; 
wrt Retnt. 266, 8646,," 1 *y4 BI6;" ase 22 
readln; 
end. 


The output from this program appears as comments at the right of the listing. 
As you can see, assigning an integer value to a variable of type shortint produces 
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a definite error, even though the reverse, assigning a shortint to an integer, is okay. 
This is because the integer type contains 16 bits of information, which simply cannot 
be fitted into the eight-bit space allocated for a shortint variable. On the other hand, 
fitting eight bits into a 16-bit space does not present the same problem. 

What happens when you try to assign a word value to an integer value ... or a 
byte value to a shortint? The program INT_TST2.PAS (which appears at the end of 
this chapter) provides an easy way for you to experiment and find out. In brief, as 
long as the word or byte values are less than the maximum valid values for integer 
and shortint types, everything is fine. With larger values however, the results 
appear as negative values. 


Typecasting Conversions Despite the problems mentioned above, there are times 
when typecasting is not only useful, but virtually essential. For these occasions, 
Turbo Pascal provides two operators for typecasting ordinal values: the ord and 
chr functions. 

The ord function changes char values into integer or byte values: 


var 
1 of Sa teger: QoS: 6nees 
begin 
a TRO TRA ZG 
1 38> OPet a oO; 
METERS fe oe te 
end. 


The chr function does the reverse, changing integer or byte values to char 
(character) values, thus: 


var 

i: integer; Weer eos oy rt Be 
begin 

1 33 965- 

a. SBCA ks Oe 

WPTCGiNt ce, Oe eT de 
end. 


Many other operators and operations used with ordinal values, such as addi- 
tion, subtraction, and so on, will be discussed later. 


Chapter 5: The Shapes of Data 61 


Enumerated Types Enumerated types are custom definitions of an ordered set of 
values and the identities that denote these values within the set. For example, an 
enumerated data type can be created using the days of the week, thus: 
type 

Week = € Sunday, Monday, Tuesday, Wednesday, 

Thursday, Friday, Saturday ); 

Following this definition, Thursday is a constant of type Week. Since the values 

of enumerated types always begin with 0 (zero), Thursday has an ordinal value of 4. 


Subrange Types Asubrange type is a subset of some ordinal data type, which is 
either predefined by Pascal or has previously been defined by the programmer. 
Thus, given the previously defined enumerated type, Week, a subrange type, 
WorkDays, can be defined as: 


WorkDays = Monday..Friday; 

In this example, Monday and Friday define the limits of the subrange, and the 
ellipsis (..) denotes a range. 

Another subrange can be defined using one of Pascal’s predefined data types: 
Cape eR a ED 

The only real requirements for defining a subrange type are that the second 
limit must be greater than the first, and both must belong to the same host type. 


Real Types Mathematically speaking, the set of real numbers is infinite, but since 
computers suffer limitations that mathematicians do not, some limitations must 
apply. Therefore, five real types are defined in Turbo Pascal, each with range and 
significant digit limitations. The five real types are: real, single, double, extended 
and comp. They are described in Table 5-2. 


Table 5-2: Real Types 
Significant Size In 


Type Range Digits Bytes 
real 2:9 10°"..1.7 x 10" 11-12 6 
single 1.5 x 10*°..3.4 x 10°8 7-8 4 
double 6.0% 10°" 47 x10" 15-16 8 
extended 34x 107°". xe 19-20 10 
comp “241,21 19-20 8 


NOTE: The comp type contains only integer values (no floating points) within the range 2°41 (« 
-9.2 x 10"*) to 2°-1 (= 9.2 x 10"). 
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Floating Point Operations Two models of floating point operations are supported: 
software floating points and 80x87 coprocessor operations. 

You select the appropriate model using the Options/Compiler menu (see 
Chapter 2), but if 8087 /80287 operation is not selected—or if the {$N+} flag is not 
set—only the type real can be used. Attempts to compile statements using the 
single, double, extended or comp types will generate errors. 

With 8087/80287 operation selected—or with the {$N+} flag set—all five real 
types can be used. If any of these are necessary but a coprocessor is not available, 
either selecting Emulation mode or using the $E compiler directive will allow the 
software to check for the presence of a coprocessor and emulate an 80x87 in 
software if the coprocessor chip is not present. 

Optimally, both choices should be selected in the Options/Compiler dialog 
menu any time extended floating point operations are anticipated. 


String Types 


The string data type is probably the most common of all, because every prompt 
written to the screen requires a string, even if it is only a message requesting a 
numerical input. Frequently, of course, messages are included as string constants 
rather than data variables, but this makes the string type no less important. 

The string type is an array of char values together with a byte value containing 
the actual length of the string. String declarations may specify a maximum size, or, 
if no size is specified, will have a default size of 255 bytes (and a total size of 256 
bytes, including the length byte). The following declaration creates a string variable 
that is 21 bytes in total size and can hold up to 20 character values: 


ASte.-s String vevi; 


Within this string, the first byte (the Oth element in the array) shows the string 
length—i.e., how many bytes in the array are actually in use. When a new string 
variable is declared, the first byte is set to zero, but the remaining bytes in the string 
are not cleared. Therefore, they may have virtually any value, depending on what 
may have previously been written to the memory locations now used by the string. 

An example of a string array structure appears in Figure 5-1, with the array 
indexes listed below each element (in both hex and decimal formats), and the 
ordinal and character values shown for each element. 

The string displayed is simply ‘This is a string!’. The string array, however, was 
defined with a size of 20 (as String|20]), so the last three elements are undefined 
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and may contain any value. Whatever may have been in memory at these locations 
has not been overwritten. 

However, since the string index (array element 0, or AStr[0]) specifies the length 
of the string as 17 characters (11h), Pascal’s string handling provisions will simply 
ignore these last three bytes. Other techniques are not restrained by the length byte, 
and can, optionally, access any element in the string simply by referencing it directly 
as an element of an array. 

Thus, while shortcuts can be applied to string handling, the inherent potential 
for error makes caution advisable. 

Both conventional and shortcut string handling techniques will be demon- 
strated presently. 


Figure 5-1: A STRING[20] Structure 





07 08 09 0OAh/10 OBh/11 O0Ch/12 ODh/ 13 





OEh/14 OFh/15 10h/16 11h/17 12h/18 13h/19 14h/ 20 


Arrays of Data 


Frequently, instead of single data items, the need is for a group of data items of a 
single type. Such groups are known as indexed arrays or, in programming terms, 
simply as an array of data. In the previous section, strings were referred to as arrays 
of characters, but an array can be of any data type, even of arrays. 

To illustrate this concept, we can declare two arrays: 
type 

STR8O = stringl801; 
var 


Numbers : arraylO..15] of integer; 
Text =: arraylO..100d: .0%s87880; 
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The array Numbers consists of space (in memory) for 16-integer values, a total 
of 32 bytes, while the array Text provides just under 8K, (8181 bytes) of space to 
hold 101 strings of 80 characters (remember, an 80-character string requires 81 
bytes). 

While previous variables were simply referenced by name, access to an indi- 
vidual element within an array requires the addition of an index. Thus, the tenth 
element in the array Numbers is called as Numbers[9]. Remember, the first element 
has the index value 0. 

Of course, within a program, the index value would normally be a variable, not 
a constant expression; thus, a more representative reference would be Numbers|i] 
where the value of i determined the element referenced. 

With the array Text, which is, in effect, an array of arrays, the expression Text[i] 
would reference the i string within the array, while the expression Text[i,j] would 
reference the j'" element of the es string. 

While arrays are normally indexed beginning with 0 (zero), this is not a fixed 
requirement. Any index pair can be used, with the restriction that index values 
cannot be type longint or subranges of type longint. Thus, an array indexed as 
array|0..26] could also be indexed as array|65..90] (to correspond to the ordinal 
values of the characters ’A’..’Z’) or to any other range desired. 

Of course, when this is done, using the range 65..90 for an example, an index 
value less than 65 will not be valid, just as an index value greater than the maximum 
is invalid. On the other hand, negative index values can also be valid if the array is 
defined using a negative index. 

Arrays are discussed further in later chapters. 


Identifying Data 


Since most of the basic data types have been introduced, the next step is to see how 
they are used to identify data and to create data instances, data constants and data 
variables. 

Programs can define two principal classes of data: constants, identified by the 
reserved word const, and variables, identified by the reserved word var. 

Constants are permanent data elements, they can only be changed by altering 
and recompiling the source code. Variables are data elements whose values can 
change during program execution in response to input or calculated events or other 
new circumstances. 
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Constant Declarations 
In Chapter 4, the example program MY_NAME used this constant definition: 


const 
Name = 'Your Name Here'; 


In this instance, a string constant was declared quite conveniently by naming 
a data element, Name, and assigning a string value to it. There was no need to state 
what type of element was being declared, because this was implicit in the data 
assigned. 

Other constant declarations might appear as: 


const 
Pt = 321815925 { Pi is a real constant } 
Ten = 10; { Ten is an integer constant } 
YES = 13 1 YES ts an tateger constant } 
NO = QO; { NO is an integer constant } 


In this example, Pi is a constant defined by a real value, while Ten is a constant 
with an integer value. The difference, of course, is that Pi’s definition includes a 
decimal place while Ten’s does not. If we wanted Ten to be a real rather than an 
integer constant, we could define its value as 10.0. 

The constants YES and NO are also integer values, but could have been declared 
as boolean values using predefined constants as: 


YES = True; { YES is a boolean constant } 
NO = False; { NO is a boolean constant } 


Remember, Pascal is not case-sensitive; True is the same as TRUE just as YES is 
the same as Yes. 

Once declared, we can use these constants in statements (program instructions) 
within a program. They are only limited by the scope of the declaration, which will 
be explained further in a moment. 


Variable Declarations 


We use variables extensively in programming to store information for use by the 
program. Unlike constants, however, the information stored in variables cannot be 
predetermined. 

The example program MY_NAME2, in Chapter 4, used this variable declara- 
tion: 
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var 
Name : string; 


Unlike the constant declaration in MY NAME.PAS, in this instance, the con- 
tents of Name are undefined but space has been allocated to contain a string value 
of up to 255 characters. 

Other variable declarations might appear as: 


var 
Name : stringl20]; 
Siz26€. 2° 4nteger 5 
Flag : byte; 
Value : real; 


{ allocates 21 bytes in memory } 
{ allocates 2 bytes in memory } 
{ allocates 1 byte in memory } 
{ allocates 6 bytes in memory } 

Declaring a variable simply provides space in memory to store some type of 
information and identifies the information type that will be associated with the 
variable identifier or name. The actual values remain indeterminate until some 


other program instruction assigns a specific value. 


Declaration Scope 


The scope of a declaration is the program range over which the declaration is valid. 
Itis determined by where and how the declaration is made. If a declaration is global, 
then the elements declared are valid anywhere within the program. 

More often, declarations are made with limited scope. They may be valid only 
within a subroutine or, less frequently, a group of subroutines. This is actually one 
of the strengths of structured programming, not a weakness. In the old BASIC 
programs, for example, all variables were global in scope. A variable X used in one 
part of the program was indistinguishable from the variable X used somewhere 
else in the program, even though each might, by intention, be used for very different 
purposes. 

With the limited scope of structured programming, however, even if a variable 
X is declared globally as a real variable, and a second variable X is declared within 
a subroutine as a string variable, no conflict occurs. Within the subroutine, the real 
X simply does not exist, as it has been superseded by the string X. In like fashion, 
outside of the subroutine, the string X does not exist. 

For a clearer example, consider this partial listing: 


const 
X = 23:.54>3 
procedure MyProc; 
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var 
x.: Integer; 
{ within this scope, the } 
Bes { constant X does not exist } 
end; 
begin 
oe { but here, the variable X } 
; { is nonexistent } 
end. 


Here, a constant X was declared globally with a real value, while, within the 
subroutine MyProc, a variable X was declared as an integer value. No conflict can 
occur between these two. Within the subroutine MyProc—between the var decla- 
ration and the closing end statement—only the variable X has any valid existence. 
Outside of the subroutine MyProc, only the global constant X is valid. 


String Constants 


One feature common to most programming is the need for prompts or screen 
messages. Being strings, they are usually created as string constants or as arrays of 
string constants. For example, three string constants are declared as an array, thus: 


type 
ErrType = ( PwrdOff, NotReady, Working ); 
Errors = arrayild..«31 of stringti0i; 
const 
ErrMsg : Errors = (€ ‘Power off', 'Not ready', 
"UWSP KINGsae” 22 


With these error messages built in, as part of the program, the instruction: 
writeln(€ ErrMsglild ); 

or 
writeln(€ ErrMsglPwrOffJd ); 


will write the appropriate error message. 


Summary 


This chapter introduced the basic data types that are used in 99 percent of all 
applications. Other types, including structured data, records and complex data 
elements, will be introduced later. 
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Defining data types is only a beginning; the essential point of programming is 
being able to manipulate data. 

The topic of data manipulation is introduced in Chapter 6, which covers the 
Pascal operators, how the principal operators work, and the basics of turning raw 
data into useful data. 


{SseseeeeeSeee2eereseeesneeee22===}) 
{ INT_TST2.PAS } 
{ demonstrates typecasting } 
{ errors with integers } 
{sHsSSeeSS2S2ee2eneezeeseeee=z==}) 
uses Crt; 
var 
a word; 
b byte; 
c integer; 
d shortint; 
begin 
clrecr: 
writeln( ' tHe Sih THE “SANT DY 
a := 65000; 
b s= 250; 
¢ - ysc9s 
qd re-02 
writetnt-a2r6, ¢:6,. °° 17 47 te). at6. 23 
c fea 
d := b; 
WPiVeeinkt: eb. o3 6, #4475 Bee eee: 
readln; 


end. 


Chapter 6 


Manipulating Numbers 


In Chapter 5, you saw some of the shapes in which data can be packaged, including 
the ordinal (integer) and real numerical types. Numerical data however, while the 
simplest of the data types, is also the type that requires the greatest manipulation 
in most programs—even those programs which appear outwardly to be non- 
numerical. 

This chapter explains the various operators and operand types that are used in 
Turbo Pascal to manipulate numerical data. A general familiarity with this infor- 
mation is useful, but the chapter includes many summary tables that you can use 
for later reference, so there is no need to memorize all the details presented 
throughout the chapter. 


Numerical Operators 


Since everything to a computer is simply numbers, all computer operations could 
be considered numerical operations. For our purposes, however, numerical oper- 
ations are more narrowly defined: they are limited to operations involving the 
integer and real data types. 

We will begin with the arithmetic operators—the expressions used to perform 
arithmetic operations on numerical data. 

Operators are classified in two types: unary and binary. Even if you haven't 
heard the terms, you are already aware of these two types. You learned about them 
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in grade school, even though little distinction was made between them, and the 
names were never mentioned. 

A unary operator is an operator that uses a single operand. In a familiar form, 
this would be an expression such as —10, where the minus sign is the operator and 
10 is the operand. A binary operator is an operator that requires two operands, for 
example, 15-7 or 4+3. 

Of course, as the examples show, some operators, such as the minus operator, 
can be both binary and unary, depending on usage. But most—as you will see—can 
only be used in one form. 

Other operators you are already familiar with include * (multiplication), / 
(division), and = (equals), all of which are binary but also have other categories 
attached. More important, these and other operators are evaluated—by the com- 
puter—in strict order of precedence, as shown in Table 6-1. 


Table 6-1: Operators and Precedence 


Operators Precedence Category 
not @ - + first (high) unary 

* / div mod and shl shr second multiplying 
+ — or xor third additive 

= <> < > <= >= in fourth (low) relational 


All of these operators follow the conventional algebraic rules for precedence: 


«= An operand between two operators of different precedence is bound to 
the operator with the higher precedence. 

«= An operand between two operators of equal precedence is bound to the 
operator on the left. 

» Expressions within parentheses are evaluated first, then treated as a sin- 
gle operand. 


Operations with equal precedence are normally evaluated in left-to-right order. 
The compiler may change the order of evaluation to generate optimum code, but 
this will not affect the result. 


Arithmetic Operators 


Operators are restricted to the types of operands (data types) that can be associated 
with their operations and to the result type generated by the operation, as shown 
in Tables 6-2 and 6-3. 
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Table 6-2: Unary Arithmetic Operators 











Operator Operation Operand Type(s) Result Type(s) 
+ sign identity integer/real integer/real 
- sign negation _integer/real integer/real 


Normally, the sign identity (+) operator is simply understood and not used. But 
it can be used if desired. The result type, of course, is the same as the operand type. 


Table 6-3: Binary Arithmetic Operators 


Operator Operation Operand Type(s) Result Type(s) 
+ addition integer/real integer/real 

- subtraction integer/real integer/real 

‘ multiplication integer/real integer/real 

/ division integer /real real only 

div integer division integer integer 

mod remainder integer integer 


With the +, — and * operators, if either of the operands are real, the result will 
be real in the {$N-} state or extended in the {$N+} state. If both operands are integer, 
the result will be integer. 

With the / operator, the result is always real. With the div and mod operators, 
both operands and results are always integer. With /, div or mod, if the second 
operator is zero (i.e., X /0), an error will occur. With the div operator, division is 
rounded in the direction of zero to provide an integer result. For example: —7 div 3 
= 2 and 7 div 3 = 2. With the mod operator, the sign of the result is the sign of the 
dividend. For example: -7 mod 2 = —-1 and 7 mod 2 = 1. 


Logical Operators 


Logical operators, listed in Table 6-4, refer to logical or bitwise operations with 
integer operands. The other type of logical operations, True/False operations, are 
known in programming terms as Boolean operations. 

With the not operator, the result is the same integer type (shortint, byte, word 
or integer) as the operand. Remember, the not operator is unary. 

The operations I shl J and I shr J shift the value of I to the left or right by J bits, 
inserting J 0 bits as padding. The result is the same integer type as I. 
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Table 6-4: Logical Operators 


Operator 


not 
and 
or 
xor 
shl 
shr 


Operation 


bitwise negation 
bitwise AND 


bitwise OR 


bitwise XOR 


shift left 
shift right 


Operand Type 


integer 
integer 
integer 
integer 
integer 
integer 


Result Type 


integer 
integer 
integer 
integer 
integer 
integer 


Boolean Operations 
Boolean operations, listed in Table 6-5, involve only True/False operators and 


return only True/ False results. 


Table 6-5; Boolean Operators 





Operator Operation Operand Type Result Type 


not negation boolean boolean 
and logical AND boolean boolean 
or logical OR boolean boolean 
xor logical XOR boolean boolean 


Boolean truth tables for the and, or, and xor operators appear in Figure 6-1. The 
and operator returns True if, and only if, both operands are True. The or operator 
returns True if either of the operands is True. The xor operator—commonly known 
as exclusive-or—returns True if one, but not both operands are True. 

The not operator, of course, is unary and simply inverts the boolean state of a 
single operand. 


Figure 6-1: Boolean Truth Tables 








AND | True | False OR | True XOR | True 


False False 


True True True 


False False False 





Boolean Evaluation 


Turbo Pascal provides two different evaluation modes for the and and or boolean 
operators: complete or short-circuit evaluation. Boolean evaluation is controlled 
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through the Options/Compile/Complete boolean eval... check box with the default 
state OFF. Alternately, the {$B+} compiler directive enables complete evaluation, 
while the {$B-} directive selects short-circuit evaluation. 

Short-circuit evaluation causes boolean operands to be evaluated in strict left- 
to-right order, halting evaluation as soon as the result of the entire expression is 
evident. Normally, this is the preferred mode, since execution is faster and code 
size minimized. 

Complete evaluation ensures that all operands of a boolean expression built with 
and and or operators are evaluated. Strict evaluation could be useful if the second 
operand were a function or procedure with side-effects that alter program execu- 
tion. 

More often, short-circuit evaluation makes evaluation possible for constructs 
that would not be valid under complete evaluation, such as: 


while € i <= ord¢€ StrLOJ ) ) 
and € StrCijd <> * * ) do 
Tet. 1 oe 
or 
White: <, Ptr <P. 2 
and not Match( Ptr*.Name, SName ) do 
Pir i= Ptr? Next, 

In either of these constructs, if the first expression is false, the second expression 
is invalid. In the first example, Str[i] would point to an element beyond the end of 
the string and, in the second example, Ptr’.Name is undefined when Ptr is nil. 

With the xor operator, obviously, complete evaluation is always necessary. 


The String Operator 


Turbo Pascal permits the use of the + operator (Table 6-6) to concatenate string or 
character operands. The result is a string. If the operands create a string longer than 
255 characters, the string is truncated to 255 characters. 


Table 6-6: String Operator 
Operator Operation Operand Type Result Type 


+ concatenation — string/char string 
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Set Operators 





Set operators, summarized in Table 6-7, consist of the +, - and * operations, and 
conform to the rules of set logic. 


Table 6-7; Set Operators 





Operator Operation Operand Types 

+ union compatible set types 

_ difference compatible set types 
intersection compatible set types 

Relational Operators 





Relational operators are perhaps the most extensively used operator types. They 
consist of the =, <>, <, >, <=, >= and in operators, as detailed in Table 6-8. 


Table 6-8: Relational Operators 





Operator Operation Operand Type 

= equal compatible simple types, 
pointers, sets or strings 

<> not equal compatible simple or 
string types 

< less than compatible simple or 
string types 

> greater than compatible simple or 
string types 

<= less or equal compatible simple or 
string types 

>= greater or equal compatible simple or 
string types 

<i subset of compatible set types 

>= superset of compatible set types 

in member of left operator is any ordinal 


type and right operator is 


Result Type 


boolean 
boolean 
boolean 
boolean 
boolean 
boolean 


boolean 
boolean 
boolean 


any set of a compatible base 


type 


Simple comparisons. Relational comparisons can only be made between 
compatible types, though comparisons can be made between real and 
integer types (type casting is applied automatically). 

String or Character comparisons. Relational comparisons are made accord- 
ing to the ordering of the extended ASCII character set. When a character 
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type is compared with a string, the character type is treated as a string of 
length 1. 

Pointer comparisons. Only two comparisons are valid: = (equal) or <> 
(not equal). Pointers are equal only if both point to the same address (or 
if both are nil). 


Pointers are compared by comparing the segment and offset values. Since the 


80x86 processors permit two logically different segment addressing schemes 
(Ptr($0040,$0049) and Ptr($0000,$0449) indicate the same memory address), point- 
ers returned by New and GetMem are always normalized (with offsets in the range 
$0000..$000F) such that evaluations will be accurate. Other pointer values must be 
treated carefully for comparisons to be made. 


Set comparisons. Only three set comparisons are possible: 

A = Bis True if, and only if, A and B contain exactly the same 

members; otherwise, the obverse, A <> B, is True. 

A <= B is True only if every member of A is also a member of B. 

A >= B is True only if every member of B is also a member of A. 
Set membership. The in operator returns True if the value of the first, ordi- 
nal-type operand is a member of the second, set-type operand. 


The @ Operator 


The @ operator (Table 6-9) is a unary operator, accepting a variable reference or a 
procedure or function identifier as operand, and returning a pointer to the operand. 
Since the pointer type is the same type as nil, it can be assigned to any pointer 
variable. 


Table 6-9: Pointer Operation 


Operator Operation Operand Type Result Type 
@ pointer variable reference or pointer 
formation procedure or function 
(same type identifier 
as nil) 


Using @ with a variable returns a pointer to the variable. 
Using @ with a value parameter returns a pointer to the stack location 
containing the actual value but does not reference the parameter itself. 
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« Using @ with a variable parameter returns a pointer to the actual param- 
eter by accessing the pointer from the stack. 

«= Using @ with a procedure or function returns a pointer to the entry point 
for the procedure or function. This pointer can be passed to an assembly 
language routine or used in an inline statement. 

» Using @ with a method applied to a fully qualified method identifier, 
returns a pointer to the method’s entry point. 


The Assignment Operator 


The assignment operator (:=) is not restricted to mathematic operations but oper- 
ates with any compatible data types. The assignment operator works by assigning 
the value of the right-hand operand, expression or function to the left-hand oper- 
and, which must be a variable of a type compatible with the value assigned. 

In algebraic expressions, the = (equals) sign is used for this same purpose, but 
in Pascal, the = sign isa relational operator only and cannot be used for assignment. 
Confusing the := and = operators is a common error in writing Pascal programs 
but, happily, the compiler warns you when this occurs. 


Summary of Operators 


A wide range of operators has been introduced. Most of these operators work in a 
familiar and almost instinctive fashion, just as you have used them in other 
circumstances ever since grade school. Granted, a few may be new or now have 
unfamiliar functions, but when they are employed in later examples, you will be 
reminded of their purpose. You can always refer back to the tables in this section 
for details as necessary. 

Now that the operators have been introduced, it’s time to look at how they are 
used with data elements. 


Using Operators with Data 


For the most part, Pascal operators are used in program statements in the same 
fashion that you would use them in common algebraic expressions. The following 
examples illustrate use of the various arithmetic operators: 


Result := A + B; Result := A * B; 
Result := A = B; Result := A / B; 
Result := A div B; Result = A mod B; 
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Using the Logical Operators 


Logical operators execute bit-wise operations on values that, most often, are 
unsigned integers (byte and word types) though shortint, integer and longint types 
are not excluded. The example program, LOGICAL.PAS, which appears at the end 
of this chapter, provides an opportunity for you to experiment and see how the 
logical bit operators function. Sample output should look something like this: 


NOT 01100 1 0 0 ¢100) R 2: not B 
equats. 72 0. 7.4..0. 2.47952 
Oe ae a oar eee R := A and B 
AND OF Tr OB) oe rete) 
equals QT :-4. 8-8 0-) 0-4 253 
OT 4-1 FT OF TF Rao R := A or B 
OR O 1.8 0 7 8 8 t480% 
equals QO t & % 3% F £9272 
oe | tt @ FOF Stes? R t= A-xoPr B 
Oe O44 4--) 8 to (100) 
ecduate 280 tT 2 heh 4-4 
OF. Oe ae eee eS SRE 4 R == A shl B 
equats 7} FB. 4 0 (246) 
G6 Th tT DOD A Sees SHR: 1 R := A shr B 
equals 00%171%741%1%710 74 € 613 


Most often, programmers use bit-wise operations to set or test flag values. But 
these most basic of the mathematical operations executed by the computer are also 
the machine operations used to execute all other computer operations, both math- 
ematical and otherwise. You may also note that a shl 1 operation is equivalent to 
division by 2, while a shr 1 operation is the same as multiplying by 2. 

The LOGICAL.PAS example program uses one bit-wise operation in the 
BINARY function to create the binary string representations shown. 


Using the Boolean Operators 


The boolean operators are used to test conditions or to set conditions for later tests. 
The unary not operator simply inverts a tested value, thus: 


if not Test then 


If Test is False, subsequent instruction(s) will execute, but if Test is True, the 
next instruction or block will be skipped. 
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The and binary operator makes the result conditional on both of the operand 
tests (or boolean variables) being True. If either or both are False, then the result is 
False. In the following example, both conditions must be met for a True result. On 
other occasions, the and operator is used differently: 

TeenAge := Age > 12 and Age < 20; 


Test := € ‘FxtStrCOJ] >= #20:> 2 ang 
C( POexe ert Zod: <b.ik “oy 


In this example, if the first test is False—that is, if the string is less than 20 
characters in length—the result of the second test—the value of the 20" character— 
is meaningless. Therefore, both must be True, using the and operator, before Test 
receives a True value. 

In other cases, a result might be determined by either of two boolean tests or 
variables, using the or operator: 


Available := Single or Divorced; 


In this case, if either of the test conditions is True, the boolean variable Available 
is set to True. 

Instill other cases, the test requires that one or the other, but not both conditions 
be True. For this purpose, the xor operator serves: 


Result = <" Day = Sunday ) xor { Date. = Holiday 2); 


In this example, either condition satisfies the requirements for a True result, but 
if both are True, the result is False. 

Since most applications use boolean tests, in one or more forms, as part of the 
primary flow controls for program execution, boolean operations appear exten- 
sively in later examples. 


Using the Relational Operators 


The relational operators provide a means for making comparisons between pairs 
of operands of compatible types. They return a boolean result, indicating that the 
comparison stated is valid (True) or invalid (False). 


Result := VarA = VarB; { equal } 
Result := VarA <> VarB; { not equal } 
Result = Yara .<' VarBb; { less than } 
Result := VarA > VarB; ( greater than } 
Result := VarA <= VarB; { Less or equal } 
Result := VarA >= VarB; { greater or equal } 
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Result := SetA <= SetB; { subset of } 
Result := SetA >= SetB; { superset of } 
Result := SetA in SetB; { membership } 
Result := Item in SetB; { membership } 


Like the boolean operators, the relational operators are used extensively to 
control program operations and will appear in examples in later chapters. 


Advanced Mathematical Operations 


The mathematical operators discussed thus far are only a small part of the facilities 
provided by Pascal to manipulate numerical data. The mathematical operators 
handle simple, common operations, but a variety of more complex operations are 
more conveniently handled by higher level library routines. 

While the first of these are relatively simple, they still provide a large measure 
of convenience. 


Ordinal Operations 


Four operations are specific to ordinal types: the pred and succ functions, and the 
inc and dec procedures. 
The inc and succ routines are similar. They are used thus: 


‘% Fe gsuect x% 2; 
or 
inet x Q2 


The inc procedure can also be used with a second argument specifying how 
much the first argument should be incremented. 


inet Ks ¥ JF 


The default—with a single parameter—is the equivalent of inc( x, 1 ). It could 
also have been written as x := x + 1. 

So, if this is so simple, why have the succ and inc routines in the first place? 

The principal reason is convenience, but the greatest convenience appears 
when enumerated types are used. For example, in Chapter 5, the type Week was 
defined as an enumerated type consisting of the days of the week beginning with 
Sunday. Manipulating a variable Today can only be accomplished using the inc and 
succ routines. Using the + operator causes an error, as shown in the following 
example: 
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var 
Today : Week; { Today can have any value of Week 

begin 
Today := Sunday; £ correct 
Today := Today +. 1; { ERROR!! 
Today := Today + Monday; { ERROR!! 
inet Teday: 33 { correct 
TOGSY Ves sucet Today 2+ { correct 


A more complete example, TestDays.PAS, is provided for experimentation at 
the end of this chapter. 

The two-parameter form of the inc procedure appears a bit curious using this 
specific type, but it is still a valid operation. Since Tuesday has an ordinal value of 
2, inc( Today, Tuesday ) increments Today by 2, perhaps from Monday to Wednes- 
day. The pred and dec routines operate in the same fashion: 


X oS.) PROS e2 
déct x: 23 
de¢ct 85°97 904 


Again, these work with any ordinal (integer) types, but are not valid with real 
types. 


Higher Mathematics 


All compilers use the same machine operations to perform mathematical opera- 
tions, but different languages offer different algorithms to implement higher-level 
mathematical functions. While other specialized languages are better as mathemat- 
ical compilers, Pascal offers a useful variety of high-level mathematical functions. 

Pascal’s higher-level mathematical subroutines fall into several groups, begin- 
ning with Abs, Frac, Hi, Int, Lo, Round, Swap and Trunc, which convert values from 
one form to another. 

The Odd function simply decides if an ordinal value is odd or even, while Pi is 
a convenient function that returns a value for this commonly required constant. 

Squares and square roots are provided by the Sqr and Sqrt functions. The Ln 
and Exp functions are used for the natural logarithms, and trigonometric functions 
are provided by ArcTan, Cos and Sin. 

Last, the Random and Randomize functions provide random number genera- 
tion, which is used for a whole lot more than simply playing games or rolling dice. 

Of these, most require little or no explanation, and some require a lot more 
explanation and training in mathematics than can be handled in this book. In 


Y 


Wee YY 
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general, if you are familiar with the mathematics involved, using mathematical 
functions in a program should present no special problems. If you are not compe- 
tent in math, the compiler cannot provide you with any significant assistance, and 
you may want to take a course in math or consult with a mathematician. If you are 
simply rusty, keep a good math text book handy for reference. 

Each of these functions is detailed individually a little later on in this chapter. 


Random Numbers 


One area of mathematics was rarely if ever mentioned in math courses and was 
almost unknown to any except a few theoretical mathematicians before computers: 
random numbers. 

This was not because random numbers are difficult, or even especially esoteric, 
but simply because random numbers—without a computer—are cumbersome at 
best, and frustrating to use in any case. In computer programming, by contrast, 
random numbers become not only convenient but almost essential. 

Random numbers are used by a wide variety of applications, ranging from 
games, where random numbers provide variety both in initial conditions and in 
responses, to more serious applications, where random numbers may be used to 
test algorithms or to encrypt data. 

True random numbers—according to our present level of understanding—can 
only be derived by observing quantum-level events such as the emission of alpha 
particles from a radioactive source, or by counting cosmic ray events. Computers 
must rely on sophisticated pseudo-random algorithms. 

A pseudo-random algorithm is a formula that begins with an initial seed value 
and recursively generates a sequence of real (or integer) values. Although the 
sequences produced are not truly random, the performance of a pseudo-random 
algorithm can be tested for two qualities: distribution of results (Q) and repeatabil- 
ity (E). The Q of an algorithm is easily tested using the Chi-Squared test; the results 
of the Turbo Pascal random function are excellent, approaching the theoretical 
optimum with a deviation well within truly random parameters. 

The second factor is repeatability: how many times the recursive algorithm can 
be executed before the sequence begins to repeat itself. Again, Turbo Pascal’s 
random function is excellent, with no detected repeatability in a run of several 
million integers. (Since small repeating sequences are natural and can be expected 
even in true random circumstances, one test looked for a repeating sequence of 100 
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integers during a 48-hour continuous run, but did not detect a repeat beyond 37 
digits.) 

Another type of repeatability is unavoidable, but can also be desirable: Each 
time a random number algorithm is called to initiate a sequence, precisely the same 
sequence of numbers will be generated. This is both natural and understandable 
when the algorithm begins with the same initial values, and any deviation would 
be indicative of serious system malfunction. 

In some applications, this type of repeatability is desirable, but not always. For 
applications where a different random sequence is desired, a second function, 
randomize, is provided, which "seeds" the random number algorithm with a differ- 
ent initial value—derived from the system clock—each time it is called. This is the 
function used to initialize most games. 

This optional repeatability does, however, provide an excellent basis for auto- 
mating testing of a variety of applications. Assigning a sequence of values to 
RandSeed, a longint variable, provides a variety of initializations while keeping the 
repeatability. 

The example program RandTest.PAS, which appears at the end of this chapter, 
provides a simple test bench for observing pseudo-random number generation, 
demonstrating three methods of initializing randomization. 

The program Life.PAS—used to demonstrate control structures in Chapter 8 
—also demonstrates random number generation used to set initial conditions for 
a simulation. 


Decimal vs. Hexadecimal 


Pascal recognizes two different numerical notations: decimal and hexadecimal. 
Decimal notation is the familiar 1, 2, 3..10..100..1000 number system that has been 
used since the Arabs invented zero. Computers, however, use binary notation—num- 
bers that would be written in machine terms as 8, 16 or 32 sequences of 1s and Os. 

These are not particularly convenient for humans, but are easily translated into 
hexadecimal notation, which uses the numerical characters 0..9, A..F (ora..f). Table 
6-10 compares the different notations. 

Of course, both the compiler and the programmer must also be able to distin- 
guish between values written in each of these systems. By default, all numerical 
entries are assumed to be decimal, unless the entry begins with the $ character. 
Thus: $1000 (hexadecimal) = 4096 (decimal) = 1000000000000 (binary) (2"). 
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Another form of notation—using a lowercase h, thus: 12ABh—is also in com- 
mon use among humans but is not recognized by most compilers. 

Hexadecimal notation appears frequently for the simple reason that it is much 
easier to keep track of computer values in this form than it is to translate them into 
decimal. 


Table 6-10: Binary vs. Decimal vs. Hexadecimal 





Binary Dec Hex Binary Dec Hex 
0000 0 0 1000 8 8 
0001 1 1 1001 9 9 
0010 ” iz 1010 10 A 
0011 3 3 1011 te. 5 
0100 4 4 1100 : AS 8 
0101 5 5 1101 ie ee © 
0110 6 6 1110 14 +s&E 
0111 ‘i 7 Tit io ae 
Mathematical Tools 


The remainder of this chapter is a dictionary-style listing of descriptions of the 
principal high-level mathematical tools (subroutines) provided by Turbo Pascal. 
All of these tools are included in the standard library (Turbo.TPL). 


Abs Function TURBO.TPL 


The Abs function returns the absolute value of the argument, which may be an 
integer or real expression. The returned value is the same type as the argument. 


Declaration: Abs( X ) 


Example: 
var 
X : real; 
Y =: integer; 
begin 
X := abst <~1.23456 2);  letshtad > 
Y = abet -123S° 23 { 123 } 


end. 
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ArcTan Function TURBO.TPL 


The ArcTan function returns the arctangent of an angle, expressed in radians, as a 
real value. 


Declaration: ArcTan( X : real ): real 
See also: Cos, Sin 
Example: 
var Ro? Feat; 
begin 
R £3 eretant 3.141529 7; { Pi radians } 
end. 


Cos Function TURBO.TPL 
The Cos function returns the cosine of an angle, expressed in radians, as a real value. 


Declaration: Cos( X: real ): real 
See also: Arclan, Sin 


Example: 
Var Rot ear? 
begin 
R ee eoet 5. 14.1529: 23 
end. 


Dec Procedure TURBO.TPL 
The Dec procedure decrements an ordinal-type variable. 


Declaration: Dec( var N [; 1: longint | ) 
See also: Inc, Pred, Succ 


Dec may be called with a single, variable, ordinal argument or with a second 
argument specifying how much the first variable parameter should be decremented. 
If Lis not specified, N is decremented by 1; otherwise, N is decremented by I. 

Since Dec generates optimized code, it is particularly recommended for tight 
loops. 


Example: 
var Na ts integer: 


begin 
I 22°33 
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N := 10; 
dec( I ); 
dec(€ N, 3 ); 
dect Hy I 22 


end. 


The Dec procedure can be called with negative as well as positive arguments, 
and can return the variable argument as a negative value—unless, of course, N is 
an unsigned ordinal type. 


Exp Function TURBO.TPL 


The Exp function returns the exponential of the argument—i.e., Exp provides the 
antilog of the Ln function. 


Declaration: Exp(X: real ): real 
See also: Ln 


Example: 
var L, RE Feat: 


begin 

LL ¢= 1.03 

R s= Expt L 2; 
end. 


Frac Function TURBO.TPL 


The Frac function returns the fractional (decimal) part of the argument. 


Declaration: Frac( R: real ): real 
See also: Int 


Example: 
var R : real; 
begin 
R = frect 1.2343 }; ‘. @, 2345" 3 
R s= fract€ <—12.3456 )>; C -0.3456 } 
end. 


Hi ~=Function TURBO.TPL 


The Hi function returns the high byte of an integer or word argument. Normally, 
Hi is used with a word argument (two bytes, unsigned) to return the first byte as 
an unsigned value. 
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Declaration: Hi( X ): byte 
See also: Lo, Swap 
Example: 

var N : word; 


begin 
N s= hi SABCD 3 { $AB } 
end. 


Inc Procedure TURBO.TPL 
The Inc procedure increments a variable argument. 


Declaration: Inc( var N [; 1: longint ] ) 
See also: Dec, Pred, Succ 


Inc can be called with a single ordinal variable, N, which is incremented by one 
or, if a second calling parameter, I, is included, N is incremented by I. 

Since Inc generates optimized code, it is particularly recommended for tight 
loops. 


Example: 
ver Ny LT 4: integer; 


begin 
1 2s 33 
N ¢= 10% 
THEM Eee 
inet Nese a3 
‘net oat ee 
end. 


The Inc procedure can be called with negative as well as positive arguments 
and can return the variable argument as a negative value—unless, of course, N is 
an unsigned ordinal type. 


Int Function TURBO.TPL 


The Int function returns the integer part of a real argument. Note, however, that the 
returned value is a real rather than an integer type. 


Declaration: Int( R: real ): real 
See also: Frac, Round, Trunc 
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Example: 
var R : real; 
begin 
R £S@ THES 22563 -23 t WseGBOO -3 
end. 


Ln Function TURBO.TPL 
The Ln function returns the natural logarithm of the argument. 


Declaration: Ln(R: real ): real 
See also: Exp 

Example: 

var R : real; 


begin 
R £=@ tnt Pr Je 
end. 


Lo Function TURBO.TPL 


The Lo function returns the low byte of an integer or word argument. Normally, 
Lo is used with a word argument (two bytes, unsigned) to return the second byte 
as an unsigned value. 


Declaration: Lo(X ): byte 
See also: i, Swap 


Example: 
var N : word; 


begin 
N := LoC€ $ABCD ); { $CD } 
end. 


Odd Function TURBO.TPL 


The Odd function is called with any ordinal argument and returns a boolean result 
indicating the argument is odd (True) or even (False). 


Declaration: Odd(N ): boolean 
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Pi Function TURBO.TPL 


The Pi function returns the value of Pi with a maximum precision of 19 decimal 
places, depending on the presence or absence of a coprocessor (Pi = 
3.1415926535897932385). 


Declaration: Pi: real 


Pred Function TURBO.TPL 


The Pred function returns the predecessor of the ordinal-type argument. The result 
is the same type as the calling parameter. 


Declaration: Pred(N ) 
See also: Dec, Inc, Succ 


Random Function TURBO.TPL 


The Random function returns a pseudo-random number. If called with a word 
parameter indicating the maximum range, the value returned is a word witha value 
N satisfying the condition 0 <= N <= Range; otherwise, the value returned is a real 
value in the range 0 <= R <= 1. 


Declaration: Random [ ( Range: word ) ] 
See also: Randomize 


Example: 
var Kos 3nteoer; 
begin 

randomize; 

X := random(10); 
end. 


Randomize Procedure TURBO.TPL 


The Randomize procedure is used to initialize the built-in pseudo-random number 
generator algorithm, deriving an initial value for RandSeed from the system clock. 


Declaration: Randomize 
See also: Random 
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Round Function TURBO.TPL 


The Round function is called with a real value, returning an integer result. The 
argument is rounded to the nearest whole number, or, if R lies exactly between two 
integers, the result is rounded to the integer with the greatest absolute magnitude. 


Declaration: Round(R: real ): longint 
See also: Int, Trunc 


Example: 

Var Is LengiaAt: 

begin 
I := round(¢ Sule 1D 2s ~ & -# 
I := poundt §-4.5678: 3; cP a 
I := round( -4.5000 }; { -5 } 

end. 


Sin Function TURBO.TPL 


The Sin function returns the sine of the argument, which is assumed to be an angle 
expressed in radians. 


Declaration: Sin( R: real ): real 
See also: ArcTan, Cos 
Example: 

var R : real; 


begin 
R s= gitnt Pt 22 
end. 


Sqr Function TURBO.TPL 


The Sqr function returns the square of the argument. The result is the same type as 
the calling parameter. 


Declaration: Sqr( X ) 
See also: Sqrt 


Sqrt Function TURBO.TPL 


The Sqrt function returns the square root of the argument, which must be a real 
value. 


90 USING TURBO PASCAL 6.0 


Declaration: Sqrt(R: real ): real 
See also: Sqr 


Succ Function TURBO.TPL 


The Succ function returns the successor of the ordinal-type argument. The result is 
the same type as the calling parameter. 


Declaration: Succ(N ) 
See also: Dec, Inc, Pred 


Swap Function TURBO.TPL 


The Swap function is called with an integer or word argument and returns a result 
of the same type with the high and low order bytes swapped. 


Declaration: Swap(N ) 

See also: Hi, Lo 

Example: 

var N : word; 

begin : 

N := swap( $ABCD ); { $CDAB } 
end; 


Trunc Function TURBO.TPL 


The Trunc function truncates a real argument, returning an integer result. The 
calling parameter is always rounded toward zero. Thus if the argument is negative, 
the truncated result is larger, not smaller. 


Declaration: Trunc(R: real ): longint; 
See also: Round, Int 

Example: 

ver Nt Ceneint: 


begin 
N82 Rene: 8.8765 3:3 oS oe 
N 28 -trune(. -9.8763) d:3 { -9 } 
end; 
Summary 


This chapter introduced the various operator types and showed most of the basic 
operators and operations that will be used in subsequent examples. The string 
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operators—and string operations—are covered separately in Chapter 7, while 
discussion of the set and pointer operations will be covered separately in more 


appropriate contexts. 


on oe 


Logical.PAS 
demonstrates Logical 
operators and operations } 


(bit-wise) } 


uses Crt; 


B, R: byte 
function Binary (¢ 
var 
TempStr: stri 
1, & byte; 
begin 
Tempstr := 
X := $80; 
for i <2. ' 
begin 
if€ V AND 


then TempStr 
else TempStr 


X := X shr 
end; 
Binary := 


end; 


begin 
clrscr; 
A 1233 
B 100; 


R := NOT B; 
writeln( ' 

writeln(¢ 
writtetn; 


R := A AND B; 
writeln¢ ' 


‘equals 


7 
Vs byte 2: String; 


Ng, 


a) 
7 


to 8 do 


x <> ° 0 
TempStr + 


ge ae 
ee 


1; 


TempStr; 


NOT > Binary (87, 
‘, Binary Cr?, 


', Binary(CA), 


4 
TempStr + 'O 


tos 
7 


{ enter new values } 


{ as desired } 
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writetnt..* AND pay CBD at So Bee ER 
writeln(€ ‘equals eNO YURI OO Re eee 
writeln; 

R32 A OR 6; 

writetnt. ! Ly BRC CA eGR Ae Feb ie 
writetn<¢:' OR Mere) ak hue. al: PR i ieee - Wee More Bh Sane pe 
writeln(€ ‘equals Oy ey OR gee Ee cee Rep toys 
writeln; 

Ro ge. A AOR 86> 

writetat. * ip CARA R Se ASS Ee ys 
wrttetac. 4 XOR Ce MADE yVUS ey Bie. ott ss 
writeln(€ ‘equals pr eee COL y UR? fo) C8) Rie, Ft 4s 
writeln; 

6B ¢= 43 

R- $2 A srl B: 

wrptetnc..' grate Gest oak ge ky? Sora Amen aera Bs ge? iter, Beta ca 
writeln(€ ‘equals gp EOP VCR 2 eo ORS ye toes 3 


writeln; 


R 32 4 Shr 8? 


writeln¢ ' > “BT AReeCAR CT Os Ass ae ort Blea ae 
writeln(€ ‘equals pp BVOBPEYUR) Bot et ass Ae Re 
writeln; 
readLln; 
end. 
(sssssSSSS55S52se52555525eee=====} 
{ TestDays.PAS } 
{ incrementing ordinal types } 
(SSSSSSSS5S555SS2ee5e5Seee2=e===} 
type 


Days_Of_Week = ( Sunday, Monday, Tuesday, Wednesday, 
Thursday, Friday, Saturday ); 
const 
Day : arraylCSunday..Saturday] of string = 
€ "Sunday', 'Monday', 'Tuesday', "Wednesday', 
 ynursday', "Friday, “Saturday’ 2; 
var 
Today : Days_Of_Week; 
begin 
Today := Monday; 
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{ Today Today + Monday; } { error } 
{ Today Today +: 1; } { arror 2 
writeln( DayL£ Today J ); 
Today := succ( Today ); 
writeln( DayCl Today J ); 
ine€ Today 2); 
writeln( DayC Today Jj] ); 
readln; 
end. 
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Chapter 7 


Manipulating Strings 


Strings are the means by which a program communicates with the user. And, toa 
large degree, programs are judged by how well they communicate. 

For example, if a spreadsheet program printed numerical data by lining every- 
thing up flush left (see Figure 7-1, left side) users would find this display annoying. 
On the other hand, with the figures "decimal-aligned," as shown on the right side 
of Figure 7-1, the spreadsheet might still be a piece of junk but the display, at least, 
would not be a reason for immediate rejection. 

Happily, Turbo Pascal provides a variety of tools for string manipulation, as 
well as for creating strings from other data types. 


The Basics of Screen Output 


Before going into the details of formatting strings, we should look at how strings 
are written to the screen. You have seen the write and writeln procedures in 
previous examples; now you will learn how they work. 

The write and writeln procedures operate in essentially the same fashion, with 
the single difference that the writeln procedure adds a CR/LF (carriage return /line 
feed) pair at the end of the output string, and then moves the cursor down one line, 
positioning it at the left margin of the display and, if necessary, causing the screen 
display to scroll to display a new line. This is true for both full screen and window 
displays. 
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Figure 7-1: Unformatted vs. Formatted Strings 


Unformatted Data Formatted Data 


123.456789 456.7800 123.45 456.78 
98765.3210 10987.60 98765.32 10987.60 


2.34000000 99.09000 2.34 99.09 
8764.23000 1.459870 8764.23 1.45 
92345.8760 987654.0 92345.87 987654.00 





Since the write and writeln procedures are the same in all other respects, the 
following explanation will refer to only one procedure, write, but will apply to both. 
Most Turbo Pascal procedures and functions have fixed parameter lists and 
must always be called with the correct number and types of parameters. In contrast, 
the write accepts a variable parameter list. The following examples, which use 
different parameter lists, are all valid: 
writetn€.' Foss. 16 a: etring!: ds: 
writeln(€ 'This item is number ', Number:4 ); 
writeln( Count:2, ' each ', ItemCItemNum], 
"at $', CostCIltemNum]:7:2, 
' = $', € CostCIitemNum] * Count ):7:2 ); 


writet "A. £otetl of ', Tettount:S, 
"ttems which come to $i, Totel:7s2:)5 


The display produced by these instructions might look like this: 


THiS 18 2 Str tag 

This item is number 123 

S eaen Gizeo Model 7. at :S: 27.45 e382. 35 
A totat @F 27 Atems which come ito '$ 123.65 


Here, the first instruction calls writeln with a single string parameter; the 
second with a string parameter followed by an integer parameter with format 
instructions; the third beginning with a formatted integer, a string, a string from an 
indexed array, another string, a formatted real value from an indexed array, another 
string and a calculated real value with formatting instructions; and the fourth with 
four parameters: a string, a formatted integer, a second string and a formatted real 
value. 
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This is pretty flexible handling, and these examples show only a few of the 
possibilities. 


Manipulating and Formatting String Data 


The write and writeln procedures accept any number of parameters, deciphering 
each parameter, in turn, to produce a single output string. 

Individual parameters may be: characters, strings, integers, reals or boolean 
values, and each is handled in an appropriate fashion. 


Character Parameters Character parameters are simply appended directly to the 
output string. Examples of character parameters might be: ‘A’, chr(65), CharA- 
rray[3], #65, #$41 or TextStr[7]. 

A width specification can also be included with a char value, in the form: ’A"4, 
chr(65):5, CharArray[3]:6, #65:7, #$41:8, or TextStr[7]:n, all of which provide width-1 
leading spaces on output before the char value is written. 

For an example, try the following: 


var 
TextStr ¢ stringiL suis 
io: integer; 
begin 
TextStr := 'This is a test‘; 
uritelnot Textstr 23 
for 1 := 1.te ord¢t. Textstrlgi 2» do 
writtetac Texts trevist. 7? 
end. 


String Parameters String parameters, like character parameters, are appended 
directly to the output string. They may be text enclosed in single quotes, text 
variables or constants, or even indexed elements from string arrays. 

String parameters may also be formatted using a width specification. If the 
width specified is larger than the string length, then leading blanks are added to 
make the output string width length. If the string is longer than width or width is 
omitted, the string is written without padding. 

Examples of string formatting are: 
weiteiat Th, ‘Shere’ e413, “17 “#3 
writetnt '(', "Medium tength':15, °*|".% 
writeln( '|', 'This Line is longer than width':15, '|' ); 
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The resulting output appears as: 


| Short | 
| Medium Length| 
[This Line is longer than width| 


Integer Parameters Integer values are translated into string expressions before 
being appended to the output string. An integer expression may, optionally, include 
a format specification in the form i:n, where n specifies the minimum length of the 
resulting string. If the integer string is smaller than n, leading blanks are added as 
necessary. If the integer string is larger than n, or if no width format is specified, 
then i is written using as many characters as necessary to represent the value. 
Conversion is always done in decimal format. 
Using a value for i of 123, examples of formatted output show as: 


writeq: fe oe ea ee Ree { l[123]| } 
WP Tteee ee eee es { | Va } 
write ( ‘|! Oy arenes zee { Brees } 


Using a value of —-123, the results appear as: 


WOVE EE Gages ph Ps % pe thee } 
WE TSO he ee eee | OS aes ok ei Ba 
wri tet? i Meee fips head } 


Real Parameters Real values are translated into string expressions before being 
appended to the output string. Two format specifications may be included in the 
form R:n:d, where n specifies the minimum length of the resulting string and d 
specifies the number of digits following the decimal place. 

If dis larger than 11,a maximum of 11 decimal places is assumed. If d is omitted 
entirely (or has a negative value), a floating point string (scientific notation) is 
written using the total string width set by the n specification. 

If n is less than 8, a default width of 8 is assumed, If n is omitted entirely, a 
default width of 17 is assumed, and the format is floating point (scientific) notation 
rather than decimal notation. 

Using a value for r of 12345.67890, examples of formatted output show as: 


WhTTOC ore ss, yal Caio at - { 112345.679| } 
WOUTeG ers est, ee { | Teas. 7 BS 
WES EARS Ot te toy. bie ae { | 12345.679| } 
write. 4") rigs, PLY hy { 112345.679| } 
WPttet * Erie. pee ene { | 1.23457E+04| } 
WPT tet ees PEt oes { | 1.2345678900E+04| } 
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Using a real value of —12345.67890, the results appear as: 


wupitet fi!) Reet, OE peg 2 { 1-12345.679| } 
weiteat Titty Freed, Pie 38 { 1-12345.7 | } 
weasel Fis Peters. 7 fay { | -12345.679| } 
urpitet "| *,. recdis, a le { 1-12345.679 | } 
weitet Pit, Feig,s 1 Oe { 1-1.23457E+04 | } 
weitec Si", PP, APs we { 1-1.2345678900E+04| } 
For a fractional value such as 0.123456789, the formatted display appears as: 
wedtet "[*) Rees, wie Fe D2 { | 0.1231 } 
wPrAtet: FT*> FIBtts eh cee { | se } 
urdtet + fte rele ay OTe ae { | Oi, Lew } 
urtte€ "1%, sss, nee { ie Vee | } 
orinet *|",) Pfetds Ee PE { | 1.23457E-01 | } 
wrttet *)hs fy Je aioe A { | 1. 23545672900E=01) > 


Boolean Parameters The final type of formatted output is for boolean parame- 
ters—or tests with boolean evaluation, as shown below: 


write (¢ > "t" 293 { | FALSE | : 
eR { | TRUE | } 


| ' 
l', 
writet * ft, 


1 
2 
Formatted Output Limits 


While individual strings have a length limit of 255 characters, output strings—writ- 
ten to the screen or to a file—do not suffer from this limitation. For an example, the 
following instruction contains a total of 21 parameters with a resulting string length 
of 419 characters: 


writeln( 'This will be a long string pes 


1) Pt > Oe 220i tae b> 

'and is extended over several Lines in the source code |', 
1220, °°) Peg! SRS deg: et 

'Like this to show what happens with a maximal string |', 
Trebs "7 ies PEOVSTO, 8] ~*y 

'which exceeds 255 characters in Length but is wrapped |', 
1se0%7 "| P*.  PeeOrtGs.. * 1 "2 | 


'each time the screen margin is reached.' ); 


and will appear on screen as in Figure 7-2. 
Of course, reading a string of this length from a file, as a string, has its own 
problems. But that’s another matter. 
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Figure 7-2: Formatted Output Limits 





This will be a long string ... | —Aiza{ ):{ 6.1234567898i an 
d is extended over several lines in the source code | “izgai 3 
@.1234567896! like this to show what happens with a maximal string H 
~231 1 @.1234567898! which exceeds 255 characters in length bu 
t is wrapped ! ~ifa4- 3-1 6.1234567896! each time the screen 
margin is reached. 


Other String Operations 


Formatting string information is only one small part of Turbo Pascal's string 
operations. Five procedures and six functions are also provided to manipulate 
strings and parts of strings. In addition, a few "tricks" supplement the string 
operations. 

For functions and procedures, the header information begins with the name of 
the routine, followed by the type (function or procedure) and, last, the name of the 
unit—if any—where the routine is implemented. Standard library routines are 
identified as Turbo.TPL. 


Chr Function TURBO.TPL 


The Chr function provides a means of changing an ordinal value (a byte value) into 
a character with the specified ordinal value. 


Declaration: Chr(I: byte ): char 


When x is an integer or byte value (less than 255), the assignment chr(x) returns 
a character with the ASCII value x. 


See also: Ord 


Example: 
var 
X° F) Bytez 
begin 
x = 633 
writel(nt x33, ' equal; chrt wy): 
end. 


Concat Function TURBO.TPL 


The Concat function concatenates a sequence of two or more strings to return a 
single string. 
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Declaration: Concat( $1, $2, ... Sn: string ): string; 


While the Concat function is like the Write and WriteLn functions in accepting 
a variable parameter list, the Concat function does not execute formatted conver- 
sions on integer or real values. All parameters must be strings or characters. If the 
total length of the concatenated strings exceeds 255, the resulting string is truncated 
to this length. 


See also: Copy, Delete, Insert, Length, Pos 


Example: 
var 
Si, S22, SS § String? 
begin 
$1 ‘THis +8 the: Tirst part *; 


S2 := ‘and this is. the second.'; 
= concat< $1, . 82) 23 

writelnt. $3 2d; 
end. 


Copy Function TURBO.TPL 
The Copy function returns a substring from a string. 
Declaration: Copy( S: string; I: byte; N: byte ): string; 


Copy returns a substring of S, beginning with the I" character and including 
N characters. If I is greater than the length of S, an empty string is returned (length 
0). If 1+ N is greater than the length of S, the remainder of the string beginning at 
[is returned. 


See also: Concat, Delete, Insert, Length, Pos 


Example: 
var 
ri. Be © Str ing; 
begin 
$1 z= "This 18 e string." 
S2 <= copyt Si, 6, * ?% 
WriteltntC St, * tg eS 
end. 


Delete Procedure TURBO.TPL 


The Delete procedure removes a substring from a string. 
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Declaration: Delete( var S: string; I: byte; N: byte ); 


N characters are removed from S, beginning at the I"" position. If I is greater 
than the length of S, nothing is deleted. If N specifies more characters than remain 
in S (including the I'" character), S is truncated to a length of I-1. 


See also: Concat, Copy, Insert, Length, Pos 
Example: 
var 
oe S* gtrene: 
begin 
5 fe. Faas +s 
wrttetint $ 33 
Geletet $, 11, 5 33 
writetnt § ); 
end. 


a: Long: string. "|: 


FillChar Procedure TURBO.TPL 


The FillChar procedure fills a specified number of contiguous bytes with a selected 
value. 


Declaration: FillChar( var S; Cnt: word, Val ); 


S is a variable reference of any type, Cnt is an expression of type word, and Val 
is untyped but may be any ordinal expression. FillChar writes Val into Cnt bytes 
of memory, beginning at the first byte occupied by S. 

Since no range-checking is used, care must be exercised and the SizeOf function 
is suggested (see example). When used with strings, the length byte must be set 
after the fill is completed since FillChar also writes over this entry with the new 
value. 


See also: Move 
Example: 
Var 
Ss: Y-etrinel30): 
begin 
Friticnere So Steg tis Ft be 


SCO] 22 #30; { set length to 30 } 
end. 
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Insert Procedure TURBO.TPL 
The Insert procedure inserts a substring within an existing string. 
Declaration: Insert(S1: string; var 52: string; Idx: integer ); 


S1 is inserted into 52, beginning at the Idx" position. If the resulting string is 
longer than 255 characters, it is truncated at 255 characters. 


See also: Concat, Copy, Delete, Length, Pos 


Example: 
var 
$1, Se: string; 
begin 
S1 := 'n inserted'; 
S2 := 'This is a string'; 


1Heertet ST, S2y 10 Fe 
writetnt §2 J; 
end. 


KeyPressed Function CRT 


The KeyPressed function returns TRUE if the keyboard buffer contains any key 
events. Otherwise, it returns FALSE. 


Declaration: KeyPressed : boolean; 


KeyPressed does not detect shift-key events such as Shift, CapsLock, Alt, Ctrl 
or NumLock, and so on but does detect all key events entered in the keyboard 
buffer, including special keys such as arrow, function or keypad keys. 


See also: ReadKey 

Example: 

uses Crt; 

begin 
while not KeyPressed do 
begin 
Writec* wetting wse.s * 2; 
detayt 100 ); 

end; 

end; 
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Length Function TURBO.TPL 
The Length function returns an integer expressing the length of a string. 
Declaration: Length(S: string ): integer; 


Since a string, in Pascal, can be treated as an array of char, the length can be 
found as the ordinal of the 0 element of the array (see example). 


See also: Concat, Copy, Delete, Insert, Pos 
Example: 
var 

LS Pe eger: 

Ss ST Inge: 


begin 
SRI See Ot ring’: 
Loss Venecht:.§ )s 
writteunt. £23": 23 

end. 

or 


Ls ee eres STO) D>: 


Pos Function TURBO.TPL 
The Pos function searches a string for the occurrence of a substring. 
Declaration: Pos(S1, 52: string ): integer; 


Pos searches S2 for the first match for S1, returning an integer value, which is 
the index of the first character of the match. If no match is found, Pos returns 0. 


Example: 
var 
i : integer; 


begin 
1 3:3. PosC 'test', "This 16 a match test string" >: 
end. 


or 


if( Poetogi, 620° 6. then { a match was found } 
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ReadKey Function Crt 
The ReadKey function reads a keystroke (character) from the keyboard. 
Declaration: ReadKey: char 


The ReadKey function waits for a key event to occur, then returns the keystroke 
to the calling instruction. If a key event is already in the buffer—i.e., unread 
keystrokes are in the buffer—ReadKey returns immediately. The key event is not 
echoed to the screen. 

The special keys (function, alt, arrow and keypad keys) generate extended scan 
codes. When a special key is pressed, ReadKey returns a null character (#00), 
leaving the extended scan code in the keyboard buffer. To detect special key events, 
a second call to ReadKey is required to return the extended scan code event. 


Example: 
uses Crt; 


var 
Ch : ener; 
Func : boolean; 
begin 
while KeyPressed do 
Ch := ReadKey; { trap any type-ahead events } 
clrser; 
repeat 
write( 'Press any key: ' ); 
Ch := ReadKey; 
Func := € Ch = #00 2); 
if Func then Ch := ReadKey; 
urttet th, ''<*, eeetthire, *2.* 22 
if Func then writeln(€ " Special Key' ) 
else writeln; 
until Ch = #03; { Ctrl-C to break } 
end. 


This example begins by trapping any type-ahead events, then reports all 
keyboard events until a Ctrl-C is entered. 
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ReadLn (keyboard) Procedure TURBO.TPL 


The ReadLn procedure is used with both keyboard entries and text files. For 
keyboard entries, ReadLn waits for a CR (Enter key) before returning a string 
(without the CR character). 


Declaration: ReadLn(S: string ); 
See also: ReadKey, Read (files), ReadLn (files) 


Example: 
var 
3. to. S212 
begin 
write< ‘Ready: ' 0: 


readln( §S ); 
writetnt $.); 
end. 


Str Procedure TURBO.TPL 
The Str procedure converts a numeric value to a string. 
Declaration: Str( N [: width [ : decimals ] ] ; var S: string ); 


N is any integer or real expression; width and decimal are optional integer 
expressions; Sis a string. Str converts N to a string expression, using the width and 
decimal format parameters in the same fashion as the Write procedure. 


See also: Val, Write 


Example: 

var 
eS 2) Ste tne ltd: 
N.S POEL? 


begin 
N 23. 923,:456>2 
stra: - Neb22>:. 8) 
writeltn€ § )-* 
end. 


UpCase Function TURBO.TPL 
The UpCase function converts a character to uppercase. 


Declaration: UpCase( Ch: char ): char; 
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UpCase converts any character in the range a..z to uppercase (A..Z), returning 
all other characters unchanged. 


Example: 

var 
S ¢ string: 
1: tnteger; 


begin 
S$ := 'This Is A Mixed Case String'; 
for 4 2 TF to. ord Stes 2 do 
SsCiJl := upcase( SEI] J; 
writeln( S$ ); 
end. 


The inverse—changing uppercase to lowercase—is not supported by any 
library function, but could easily be implemented, if desired, thus: 


funeétion DnCase( Cs: char 2: char; 

begin 
14 ¢. 4H CYA oats?) then theC C6, S20 2; 
DnCase := C; 

end; 


1 aa 
reir 3 


fad 


iy ey 


ees 


Tethe 


ae 





Chapter 8 


Creating Tasks and Controlling the Flow 


Previous chapters introduced program data elements, the basic operator types, 
library functions and procedures, with minimal examples demonstrating their 
operation. Program functions and procedures have also been introduced, showing 
the large-scale structural elements used by Pascal. 

But Pascal is a structured programming language on all levels. Structural 
elements also appear within the larger program elements—i.e., within the main 
program body and within functions and procedures. On this scale, the structural 
elements are known as program blocks, which are controlled by loops and other 
decision structures. 

Before examining these large program elements, however, we'll take a look at 
the smaller program elements, statements and expressions, which are used to build 
them. 


Statements and Expressions 


Program statements are the basic elements of any program. They can be defined as 
one or more expressions and/or instructions specifying a desired task. You've 
already seen program statements used to illustrate operations or to call functions 
or procedures. 

Individually, program statements can be simple or complex. Asimple statement 
might be: 


writeln( 'This is a program statement' ); 
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A complex statement might appear as: 


if Day = Saturday then 


writeln( ‘Party time!' ) 
else 
if Day = Sunday then 
writeln(€ 'Weekend''s almost over!' ) 
else 
if€ Day = Monday ) or 
( Day = Tuesday ) or 
( Day = Wednesday ) or 
( Day = Thursday ) then 


writeln€ ‘Another work day' ) 
else 
writeln(€ 'Thank God, it''s Friday!' 73 


How can both of these examples be identified as single statements? Quite 
simple—each is terminated by a single semicolon (;)}—the statement terminator. 

The first example consisted of a single expression, but the second example, 
while still a single statement, is created from a whole host of expressions, including 
three writeln expressions, one complex if..then..else expression and several boolean 
expressions. (Note: This same task can be expressed in a different and much cleaner 
form, which you will see in a later section. This current example was constructed 
this way for illustration only.) 

In general, we will be less concerned with writing complex statements—though 
we may use them at times—than with writing complex blocks of simpler state- 
ments. 


The Begin..End Block Statements 


Several levels of structure are used in Pascal programs. At the lowest level, the begin 
and end statements are used as block delimiters. At higher levels, they indicate the 
beginning and ending of procedures and functions and even enclose the body of 
the main program. 

Within the main program—or within subroutines—block delimiters are used 
to group related program instructions. This allows blocks of instructions to be 
controlled by conditional statements or loop statements. 

Figure 8-1 shows a series of nested begin..end statements with multiple levels 
of nested blocks. 
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Figure 8-1; Structure Using Nested begin/end Statements 


begin 
... € statements } 
| begin 
| .e. & Statements } 
| | begin 
| | i> { statements } 
= oa begin 
| | { statements } 
| | | \ end; 
| | : { statements } 
| | end; 
| \ end; 
| { statements } 
| begin 
| { statements } 
| ( end; 
| end; 


Of course, the only reason for grouping a series of statements would be to use 
some form of control to decide whether or how many times to execute them. For 
this, some type of conditional statement is required. 


Conditional Statements 


Pascal provides several conditional controls, but they can be separated into two 
categories: decision switching and loop controls. 
In the first category, decision mechanisms, the if..then..else statements and the 
case..of statements provide branched decisions with varying levels of complexity. 
In the second category, loop mechanisms, the for..to..do, while..do, and 
repeat..until loops offer several forms of controlled repetition. 


The If.. Then..Else Decision 


The simplest conditional statement is the if..then..else statement which was used 
earlier as an example of a complex statement: 


TT «<«tHON <> 
olee@ 11s c.tNen«,s 
else if..then.. 
else.. 
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This example was actually a very unusual structure, which combined three 
if..then..else statements (with several conditional or statements). Much more often, 
a simple if..then statement is used in the form: 


1ft ¢€ condition} -then 
begin 

{ statements to be executed } 
end; 


The else portion of the statement is optional, but can be included, as in: 


1f < condition} then 
begin 
{ statements to be executed } 
end else 
begin 
{ alternate statements } 
end; 


Notice though, that in this format the end delimiter in the first block does not 
have a semicolon to indicate an end of statement because the statement continues 
with the following else. 

The else conditional could have been followed by a single statement (without 
the begin..end block), or then might have specified a single statement to be executed 
instead of a block of instructions. Of course, any of the statement blocks can include 
other conditionals with their own nested statement blocks. 

Thus, this is very much a “‘mix and match” situation, where the structure can 
be tailored, at each level, as required, to perform a portion of a task. And quite 
complex conditionals can be tailored for complex decisions. 


The Case..Of Decision 


The case..of statement supplements the if..then conditional and provides a simpler 
method for handling many complex branch conditions. 

Recall that an earlier example of a complex statement used an inefficient series 
of if..then..else statements. An easier way to handle the same task was promised, 
and the case..of statement is precisely that alternative. 

Using the same example, but translating the stacked if..then statements into a 
case statement produces a result like this: 


case Day of 
Saturday : writeln(€ 'Party time!' ); 
Sunday : writeln(€ 'Weekend''s almost over!'! S. 
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Monday, 
Tuesday, 
Wednesday, 
Thursday : writeln(€ ‘Another work day' ); 
Friday +: writein( 'Thank Ged, it''s Friday!" 9; 
end; { case } 


In the case..of statement, an enumerated variable is used, while each individual 
enumerated value is listed with the appropriate action (response) to be taken when 


the variable has that particular value. 
This is the equivalent of saying: 


if Day = Saturday then 
if Day = Sunday then 
if Day = Friday then 


The case statement is not only a more efficient expression, it is also much easier 
to write, in several ways. First, the individual case instances can be grouped in any 
order. 

Second, instead of listing the individual cases Monday, Tuesday, Wednesday, 
Thursday, a simple range statement can be used, thus: 


Monday..Thursday : writeln(€ ‘Another work day' ie - 


This grouping of cases can be done for any sequence of enumerated instances, 
such as 5..12 or F.N and one or more sequences can be combined. For example, to 
select both the alphabetical characters and the numerical characters within a single 
case instance, the case statement might be written as: 


case Ch of 
'g* 2 FEr, 
caer ee 
tat. te" + sce, Seresponec: 7 
Third, the entire example case statement can be rewritten using a default else 
case to handle all cases not specifically handled by individual cases, thus replacing 
the sequence of “same” cases. 


case Day of 
Saturday : writeln( ‘Party time!" ); 


Sunday : writeln( 'Weekend''s almost over!' 3 
Friday : writeln(€ 'Thank God, it''s Friday! ' diy 
else writeln( ‘Another work day' ); 


end; ¢{ case } 
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Finally, in many applications, only selected values might be provided with 
specific handling and all other values simply ignored—the equivalent of an empty 
else statement. 

If more than one program statement is to be used in response to an individual 
case, then a begin..end block is needed to enclose the statements, thus: 


case Day of 
Saturday : begin 
{ multiple statements } 
end; 


end; { case } 
case statements can nested as well, thus: 


case A of 
1 ££ Cee: 8 of 
X 
. SEG Ga a aa 
end; { case B } 

y Kapem Lng ie 
end: 4 8ese A? 

Note that each case statement requires a matching end statement, just like a 
begin..end block. The comments, such as { case A }, following each end statement 
are entirely optional. They help keep things straight, especially when case state- 
ments extend over a page, or two or three. 


Which Switch? 


The if..then..else and case..of decision statements are two quite different approaches 
to switch decisions, each providing different capabilities and having different 
limitations. 

The case statement is limited because each selector must be a constant value. 
Variable case instances cannot be used with case selection, though an if..then 
selection can use any type of statement that can be subjected to a boolean test, even 
comparing two variables. 

A second limit is that the case selectors can only be byte-sized or word-sized 
values, although they can be either signed or unsigned values. Thus, acceptable 
values may be enumerated, char, shortint, byte, integer or word types. Therefore, 
for strings or real values, the case decision is not an option, and only an if..then 
decision can be used. 


Chapter 8: Creating Tasks and Controlling the Flow 115 








Also, for simple branches, the if..then decision is easiest, even though a case 
decision can be written with a single selector (and is perfectly valid). 

These restrictions aside, the only remaining considerations are your own 
preferences. You may use the switch you feel is most appropriate in any particular 
circumstance. 


Loop Statements 


Loop statements are used to repeat one or more statements. They occur in three 
forms: 


» the for loop executes a specific number of times 
» the while loop executes as long as a test condition remains true 
«= the repeat loop executes until a test condition is satisfied 


Each of these three loop types offers a different set of features and is intended 
for a different purpose, but almost any loop requirement can be implemented using 
any of the three types. The difference is simply that some forms are more convenient 
than others. 


The For..To..Do Loop 


The for loop causes a statement, or block of statements, to repeat a set number of 
times while incrementing a single count variable. This also appears in reverse form 
as a for..downto..do loop, decrementing the count variable while executing. The 
operation is essentially the same in both cases: 


to TO do wei teine TZ . 25 
O downto 1 do writeln( i:2 ); 


for 1 == 4 
for i = -7 

These examples just write a series of numbers, but the for loop can be used with 
begin..end block delimiters to repeat any number of statements, and, at the same 
time, the count variable can also be used as a parameter when calling other 
procedures within the loop. 

The limits do not need to be constants, but can be variables themselves, with 
the restriction that the control and limit variables must 1) be ordinal types, and 2) 
be assignment compatible. 


for i := N to M do 
begin 
SubProcA( i ); 
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{ other instructions } 
end; 


Even if the initial and final values are expressed as variables, their values cannot 
be changed while the loop is executing, even though the control variable remains 
subject to a new value assignment. 

For example, the following code counts by twos, even though the for loop has 
no precise provision for incrementing by anything except ones. 


TOC SL Se SST as 
begin 
Eiko, Sek eee ee 
WrtItelLAc ds2 
end; 


It is only fair to warn you that this type of manipulation in a for loop can be 
hazardous. To see how, rewrite the inc statement as: inc( i, 2 );, then sit back and 
watch what happens. (Note: Ctrl-Break will interrupt execution.) 

The reason for this result, of course, is that the terminating condition, i = 10, is 
never met because i skips directly from 9 to 12. Therefore, modify for loops with 
caution. 


Nested For Loops 


Any type of loop, or any type of block structure, can be nested, but for loops are 
probably the type most commonly used with nesting. Here is a simple example of 
nested for loops: 


uses Crt; 


var 
to ¥e BE byte: 

begin 
clrser: 
for 2.32.7 .doewnto: +. :do 
begin 


TORTACC £2. 2. 4+: 83 
TOC. FSO 1 0°. 23: ao 
Tore 33 1. te yi doe 
begin 
SOtoxyt x." By °y¥. 03 
MOT te tC: Fee he) 
end; end; 
readln; 
end. 
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Notice that the for y loop statement is followed by the for x loop statement 
rather than a block delimiter. This is because everything controlled by the second 
(x) loop statement is treated as a single block by the first (y) loop statement. Also, 
the x loop shows how the variable y can be used as a limit variable instead of using 
a constant value. 

The Life.PAS example program at the end of this chapter shows further exam- 
ples of the for loop. 


Local Variables with For Loops 


One restriction is applied to for loops: The counting variable—i in the preceding 
examples—must be local to the procedure or function where the loop is used or 
must be global to the entire program. Loops cannot use control variables that were 
declared at a higher procedure level, though limit variables can be declared any- 
where and can be calling parameters. A partial example follows: 


var 
ly Jy K-2t “VHteger; { global } 


procedure LevelOne; 


var 
468 Ynteqer; { Local to this Level } 
procedure LevelTwo; { subprocedure within LevelOne } 
var 
b § tnteger; 
begin 
iL a ae ee 3° ae oe: > ae { all are otobally valid } 
for &..t= 4 to. k- ae « «=, » { a is -tavetia,.not. local 2 
for. b&b f= 9 £6 KOO as. ves Cb te locatly vatid? 
end; 
begin 
for 1°4%.4) toe K G6) «Se { all are globally valid } 
for @ S24) 86°80 + e-oae fa is Locally vatid } 


This restriction is a safety device, but also has loopholes. In earlier versions of 
Turbo Pascal, no restriction was implemented and variables declated at any level 
were used freely throughout. A common practice was to declare two or three global 
variables as i, j, k, and then use these in the program as loop variables. Because a 
variable might be used for a loop in one procedure that called—within the loop— 
another procedure which used the same variable for a different loop or purpose, 
subtle errors did occur. The restriction against variables declared in one procedural 
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level being used as loop variables in a subprocedural level removes one level of 
error. 

Global errors still present a potential for error. Therefore, declare local control 
variables anytime a for loop will be used and leave global variables for global values. 


The While..Do Loop 


A for loop is fine when a statement or block needs to be executed a set number of 
times, but more often, you need to repeat a statement or block an indefinite number 
of times, either while a certain condition is true or until a condition becomes true. 

The first case is usually handled using the while..do structure. For a simple 
example, the following code fragment can be used to trap type-ahead keyboard 
events, and continues to execute as long as any keystrokes are present in the 
keyboard buffer: 
while keypressed do 

Ch := readkey; 

In this form, if keypressed is never true, i.e., the keyboard buffer does not hold 
any keystrokes, the controlled statement is not executed at all. In this case, that is 
the desired result, because otherwise, the readkey function would wait for a 
keystroke. This way, if no keystrokes are already present that need to be cleared 
out, the test fails immediately and skips the controlled statement. 

When multiple statements should be repeated, the begin..end block delimiters 
can be used in the same fashion as shown with the if or for statements. 

The C compiler language also offers an inverse form: do..while, which allows 
the controlling condition to be tested after the statement or block has been executed. 
While Pascal does not offer this specific structural form, the equivalent is provided 
as in the Repeat..Until loop. 


The Repeat..Until Loop 


The repeat..until loop is virtually identical to C’s do..while loop, except that the 
controlled statement or block is always executed at least once before the controlling 
condition is tested. The form for a repeat..until loop is quite simple: 
repeat 
: { one or more statements } 

until {: tes condition}; 

The repeat..until loop does not require begin..end block delimiters to enclose 
multiple statements; any number of program statements can appear within the 
loop. But remember, all statements within the loop will be executed at least once 
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before the control condition is tested. Then, if the condition is not True, the loop 
will repeat until the condition is satisfied at the end of the loop. 

Both the while and repeat loops could be implemented relatively easily by 
manipulating the control variable of a for loop structure, though not as easily as 
using the while and repeat loops themselves. 


Subroutine Testing 

A variety of control structures have been discussed, using a variety of direct tests 
to execute the control structures. Frequently, however, the tests needed for control 
execution are not as simple as those used in our examples so far. For more complex 
circumstances, subroutine testing is a practical alternative. 

In its simplest form, subroutine testing consists of calling a function or proce- 
dure, with or without testing parameters, and using the result(s) to control execu- 
tion of a local structure. 

Perhaps the simplest example of subroutine testing could be written as: 


repeat until keypressed or MyTest; 


In this example, the repeat loop itself does nothing except wait for a keyboard 
event—for some key, any key, to be pressed. But this is still an example of a 
subroutine, the keypressed and MyTest functions, being called to control the 
execution of a structure. 

In the preceding example, the assumption is that MyTest returns a boolean 
result, but this needn’t always be the case. The called function might return some 
other type of value requiring further comparison, thus: 
repeat 

; { some task } 
until MyTest = Completed; 

In other cases, the test might depend on a value returned by a call to a 
subprocedure within the control loop, thus: 


repeat 


TestProc( VarA, B, C ); 
until VarA = TestVar; 

Technically, this is a direct test, but the value of VarA depends on a subproced- 
ure call within the loop. 

Various examples of subroutine testing in more detail appear in later chapters. 
For the moment, simply keep in mind that tests do not necessarily need to be limited 
to simple statements, because structured programming extends to all levels. 


120 USING TURBO PASCAL 6.0 





Summary 


Programs without control loops and decision branching would be pretty ineffec- 
tive. The efficiency of your programming will depend largely on your own facility 
in using these features. 

The examples showing these features in this chapter are pretty simple, but they 
show all of the principal elements necessary to use these controls correctly. More 
complex examples appear in different contexts later in the book. 

Three example programs, Weekdays, Weekdays2 and Life, listed below, dem- 
onstrate topics discussed in this chapter. The third program, Life, demonstrates 
several control and decision structures. 

Next, in Chapter 9, the topic is complex data types. There, you will be intro- 
duced to a different type of structure, structured data, which supplements pro- 
gramming structures. 


(SSSSSS5S2SSSSSeSeeeeeeesseeseese===} 
{ Weekdays.PAS } 
{ illustrates a complex statement } 
(SSSSSSSSSSSS5S5 See 5eeeeeeeee====2} 


type 
Days_Of_Week = ( Sunday, Monday, Tuesday, 
Wednesday, Thursday, Friday, Saturday ); 
var 
Day : Days_Of_Week; 
begin 
for Day := Sunday to Saturday do 
begin 
write(€ ord( Day ), ! = sige ie 
if Day = Saturday then 
uri tetn€ "Party time! '.|) 
else if Day = Sunday then 
writeln( 'Weekend''s almost over!' ) 
else if(€ Day Monday ) or 
( Day Tuesday ) or 
( Day Wednesday ) or 
( Day Thursday ) then 
writeln(€ ‘Another work day' ) 
else writeln(€ ‘Thank God, it''s Friday!' ); 
end; 
readln; 
end. 
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{sessssesteerseseesescesesssssesese=s=} 
{ Weekday2.PAS } 
{ illustrates a case..of statement } 
{e2eesaeseneereseetesseessssssestccez=} 


type 
Days_Of_Week = ( Sunday, Monday, Tuesday, 
Wednesday, Thursday, Friday, Saturday ); 


var 
Day : Days_Of_Week; 
begin 
for Day := Sunday to Saturday do 
begin 
write ( ord( Day vy, * = oan 
case Day of 
Saturday : writeln( ‘Party time!‘ ); 
Sunday : writeln(€ 'Weekend''s almost over!" ); 
Friday : writetint "Thank God, ?t**s-fritday!*" );7 
else writeln(€ ‘Another work day' ); 
end; { case } 
end; 
readln; 
end. 
{sesesesssssssssstssssssssseesessszszz} 
{ Life.PAS } 
{ demonstrates control structures”~ } 
{ tev BOE <-¥e TUN @6. WELL -s2% } 
{Sseeeeeeesesetessrsesessessssseeszzz==} 


uses Crt; 


const 
MaxX = 80; 
MaxY = 23; 
Step = 10; 
var 


Done, Select : boolean; 

Cells : arrayl 1..2, 1..80, 1..235 J] of boolean; 
Pause : integer; 

Ch > Chats, 


procedure Introduction; 
begin 
eLPreecr: 
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writeln(€ 'The game of Life simulates the growth of a', 
'" special type of animalcule within' ); 
writeln(€ ‘a 2-dimensional world simulated by the', 
" computer: In the good olde days' ); 
writeln(€ "(B.C. or before computers), this game was', 
" played with pencil and graph' ); 
writeln(€ 'paper Cusually by students with lots of time', 
" on their hands). Today, computer' ); 
writeln(€ ‘simulation makes a variety of forms of Life', 
'" easy to investigate.' ); 
writeln; 
writeln(€ 'You will be offered two initial choices of', 
’ initial world state: 1) randomly' ); 
writeln€ ‘generated or 2) preset showing several blinker', 
" forms and one flyer but the' ); 
writeln€ ‘evolution of the world of Life beyond this', 
' point is governed entirely by' ); 
writeln( ‘three simple rules.' ); 
writeln; 
writeln€ 'In each generation, each cell in the world', 
' is born, Lives or dies dependent' ); 
writeln€ ‘on the number of Living cells neighboring', 
1t. The rutes of Lite eres" 9D; 
1) if a cell is dead but has exactly three', 
neighbors, a new animalcule is' ); 
born in the next generation,' ); 
2) 47 @ cel teiattve and has 2 or’ 3', 


| 
writetn(—' 
| 
4 
' 
" neighbors it will continue to tee 23 
' 
' 
' 
Y 


writeln¢ 
writeln(¢ 
writeln¢ 3) if a cell is alive but has fewer than', 
2. or more than-Snetehbors, it wiht? >> 

die of loneliness or suffocate from', 
overcrowding." X32 


writeln¢ 


writeln; 
writeln(€ "You may also alter the source code to', 
' investigate new patterns or to test new' ); 
writeltn(€ ‘rule sets. Have fun.' ); 
writeln; 
write€ "Press ENTER to continue' ); 
while keypressed do Ch := readkey; readln; 
end; 


procedure Clear_Cells; 
var 

1g Jee <2 AM eaer) 
begin 

for. t ge? to 2° do 
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for j == 1 to MaxX do 
for k := 1 to MaxY do 
Celtel tse to B # = 
end; 
procedure Prompt; 
begin 
gotoxry€ 1, 25 oF ehreai 
write( 'Speed: ', (1000-Pause) 
’ Press < for slower, 
'or ENTER to quit '); 
end; 
procedure Write_Screen,; 
var 
tos integer; 
begin 
for i := 1 to MaxX do 
for 3 = 1 to MaxY do 
142 Celtst tea ty tvs ae 
begin 
goteoxyt Tp, 325 
14t. Cottet ce te 3 a 
COtLLSE Vy te 3-3-8235 
end; 
Prompt; 
end; 
function Count_Neighbors( X, Y 
var 
lz Jd» Result, THA, TPT integ 
begin 
Result := QO; 
Tor: 4 = -1 to 1 do 
for j := -1 to 1 do 
begin 
Tox 3:= X*i; 
ToY = Yj; 
if Tex < 1 then .tpAr 2= Fi 
if TpX > MaxX then TpX 
if ToY < 1 then. TpY := MB 
if TpY > MaxY then TpY 
'* Celtst-1, Tex, Tet 2 
end; 


TE Cetilal 1,-Kk, ¥ 2 2° then -da 


False; 


div 10, 
* Tor taster, * 


Gettat' 2, te 3 2° 2 Baer 

> then writet 's" 2) 
else writet.? * 2; 

etisl 2, Ties ae 

byte ): byte; 

er; 

axX else 

= 4% 

axY else 

= ly 

then inc(€ Result ); 

eC Resutt.2; 
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Count_Neighbors Resul 


end; 


procedure Run_Life; 
var 
123 
Ext 
begin 
Exit 
repeat 
Write Screen; 
delay( Pause ); 
Tor .-4 1° to MaxX do 
TOP. 1 to MaxyY 
case Count_Neig 
2 Cells 
5 Cells 
else Cells 
end; 
while keypressed do 
begin 
Ch readkey; 
case Ch of 
wrk A See F 


integer; 
boolean; 


False; 


T 


es if 
#$OD 
end: << case =} 
Prompt; 
end; 
until Exit; 
end; 


Ex i 


procedure Preset( Pattern 

var 
i, 

begin 
Clear_Cells; 


Age woe Tnteger : 


A 23 faxes aiv 23 
Y s= MaxY div 2; 
case Pattern of 
1: begin { blinker 
for 4 2 T:to'-S 
begin 
Celts <2, 74 








t; 

do 

nDoreC.a, . 7): of 

Cypser ee COLLEGE ae ye Fs 
G2 eid oa ee Tes 

beep ap hae Pet ees 


Pause > 0 then 
dec€ Pause, Step ); 
Pause < 1000 then 


inc€ Pause, Step ); 
t = True; 

byte ); 

ee 

do 

Ves 2 ee oTrues 
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Celtsi2;sMaxk-5. ¥ri-d = Trae; 

Celltst 2, 4410, MaxY-5 J t= True; 

Celisl 2» 33 Y-7 J ¢=° True; 

Cellet 2, Xt, Yor"! J = True; 
end; 


end; 
2: begin { twin blinker +} 


X := MaxX div 2; 
Y := MaxY div 2; 
for 1 Pe X46. t0 Mes. do: CeLiet 2,1; Yi <= True; 
end; 
3: begin { flyer launcher  } 
Tor 4 2 Se ede. Cevist 2, te 3 J := True; 
for + = 4 *6 Sido Cetlst 2, i*t4, Yi. id 22 True; 
end; 
end; { case } 
end; 
procedure Select_Preset; 
var 
is fF & Futeger; 
begin 


gotoxyt 1, 1-.22 ebreoery 
write€C "Select pattern: 1) blinkers .. 
‘es Swine: “SI ttver  <Tr2la> "3% 
repeat 
Ch := readkey; 
unest Ch tw £7 9*.%78B" de 
VELL. Sits Te fF IZ 
Preset( i ); 
end; 


procedure RandSet; 
var 

1: wHtecger? 
begin 

Clear_Cells; 

randomize; 

for i i= 1 toe 409 do 

CellsC 2, random(MaxX)+1, random(MaxY)+1 J] := True; 

end; 


begin 
Pause := 100; 
repeat 
cLYreecr? 
write "Would you like instructions CY/N? 7? ° 2); 
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if€ upcase( readkey ) = 'Y' ) then Introduction; 
repeat 

Select := true; 

cirscr s 


write 'Select Initial conditions: *, 
" 4) preset 22 ‘nandom patterns CVE2Z2¢*% 33 
Ch := readkey; 
case Ch of 
aro? Select Preset; 
"e" sg RandSet; 
else Select := False; 
end; 
Girecr: 
Run_Life; 
until Select; 
ectoxy< 15.2533: ebtreets 
WETtEL Try agatn Chie Pt 2a 
Done := upcase( readkey ) <> 'Y'; 
until Done; 
end. 


The 25x80 screen is rather small for the best results; a graphics display is better. 
Still, even this minuscule world does provide enough room for the “flyer” option 
to grow a launcher, which, as it crawls, will fire off two “flyers” —five unit animal- 
cules that fly by changing shape across the world. Flyers progress through a 
sequence of four shapes as they move. 

In a larger world, the launcher figure will continue indefinitely, leaving small 
blocks of four units behind. The launcher dies when it runs into its own debris or 
into one of the launched flyers. 

Also, note that the world is closed, or wrapped, and a flyer leaving the bottom 
of the screen will reappear at the top. The same is true for the right and left margins. 

Try your own figures, and see how they do. 


Chapter 9 


Complex Data Types 


So far, we have discussed programming structures at two different levels: structures 
composed of procedures and functions and structures within procedures and 
functions. A third level of programming structure is equally important: data 
structures. Data structures provide a means for creating groups of related data 
items as well as for treating the individual collections as single items. A good 
analogy is a card index, containing names, addresses and phone numbers. If you 
were creating such a card file, a reasonable approach would be to enter all infor- 
mation about a particular person or company on a single card. Using the program 
data structures introduced thus far, your best choice might be to use a long string 
to hold all of this with some special symbol to break the information into segments. 
This approach might look like this: 


Janet Smith | 1234 E Street | Hometown, AZ 71234 | 444 | 444-5678 Zz 
John Smith | 234 West 56th | Anytown, CA 81234 | 555 | 555-1234 | 567! 
Ken Smith | 34 North 12th | Erewhon, OR 91234 | 666 | 666-9876 | 8765 | 


This is relatively understandable for humans, but how would you tell the 
computer that you want a list of everyone in the data file who lives in Anytown, 
California, or everyone in area code 333? How would you extract and dial John 
Smith’s phone number, with a telephone extension if applicable? 

Well, these things could be done, even with such an awkward data format. But 
they can be done much easier and faster if the data is stored in a data structure. 
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Data Structures 


The first step in creating a data structure is to decide what elements are needed. In 
the preceding example, the data string was subdivided into fields for Name, 
Address, City-State-Zip, Area Code, Phone Number and Extension. We can use 
these same fields in constructing a data structure. We will add a field to hold a 
Company Name, since the presence of phone extension numbers suggests that 
some entries are personal and some business. 

Individual data elements requiring provisions for storage are listed in Table 9-1. 


Table 9-1: Data Elements for a Record Structure 





Field Size 

Name string[30]—most names will fit 

Company string|20]—use abbreviations if necessary 

Address string|20]—should be enough 

City string|15]—enough for most cities 

State string|2|—only two characters for state abbreviations 
Zip string[10]—most are 5 digits but some use 4-digit ext 
Area string|3]—only 3 digits required 

Phone string[8|—XXX-XXXxX is the usual format 

Ext string|5]—usually 2, 3 or 4 digits, but sometimes 5 


This data structure does not provide for international entries, but we can 
remedy this later using a different, complex data structure. Also, this data structure 
uses only strings. A different type of structure will be demonstrated when we move 
on to mixed data types. To create our data structure, we must begin with a type 
declaration, defining a specific structured data type. 


The Type Declaration 
The type declaration for this data structure would look something like this: 
type 
AddData = record 
Name 1 Stringlsoi: Company : stringl20]; 
Address : stringl20]; City . Strinetlis.: 
State : Strinegleus Zip y St Ping tlds: 
Area : string lad: Phone cr Striagced: 
Ext etnrinet st» 


end; { record } 
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The type declaration begins by giving the name AddData to the new data type, 
then uses the reserved word record to specify the beginning of a structure block. It 
ends with the end statement, identifying the extent of the block. 

Within the block, the individual elements—more commonly called fields—are 
defined in this example as strings of specific lengths. 

The type declaration, however, only provides a new data type. Before this data 
structure can be used, a variable, or an array of variables, of this type must also be 
declared. 


var 
Entry : AddData; 
List s erraye—?,..100] of AddData; 


The Entry item is one instance of the data structure. It allocates 122 bytes of 
memory for storage, while the List array allocates 12,200 bytes. 

Note: If you wonder about the difference between the 122 bytes of the structure 
size (call sizeof(Entry)) and the 113 string bytes defined in the structure (add them 
up), remember that every string includes a one-byte length specification, not for 
the length of the string variable itself, but for the length of the data stored in the 
variable. 

This suggests that strings might themselves be an example of a complex data 
structure defined something like this: 


string : record 

Length : byte; 

Letters « arrayl1..2531 6f char; 
end; 


That is essentially what a string really is, so at least one complex data type has 
already been introduced and used in several fashions. 

With AddData, we have created a complex data type built from another 
complex data type. This demonstrates once again how structure can be extended 
at any level of programming, and it will be demonstrated further in later examples. 

Now that the data type has been created, what about using it? 


Data Field Entry 


The data fields in the AddData type are all string fields; they accept only string data 
assignments. As with other data elements, the assignment operator (:=) is used, but 
with a slight difference: 
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Entry.Name := ‘John Smith'; 
Entry.Company := ‘Amalgamated Limited'; 
ListCn].Name := 'Jack Jones'; 


These are known as fully-qualified record fields, consisting of the name of the 
data field (Entry or List[n]), a period (acting as an associative delimiter) and the 
field name (Name, Company, etc.). 

Fully-qualified field names are awkward, but happily, they are not always 
required. An alternative is provided in the form of the with..do statement. 


The With Statement 


The with..do statement is a shorthand form used, witha block delimiter, to reference 
record fields or object methods and fields. Normally, when a record field or object 
method or field is referenced, a “fully qualified reference” is required in the general 
format: 


RecName.field1 := VarXx; { assigns a value to a field } 
ObjName.method1( VaryY ); { calls an object method } 
ObjName.field1 := VarzZ; { assignment to an object field } 


Note: objects will be introduced in a later section. 
Using the with..do statement provides a format that is simpler for the program- 
mer but does not affect the construction or execution of the program itself: 


with RecName do 


begin 
fietdt se Vary; { assigns a value to a field } 
VarX := field2; { accesses a field value } 
end; : 
with ObjName do 
begin 
method1( VaryY ); { calls an object method } 
field! := Varx; { assigns a object field value } 
end; 


Multiple record or object instances can be used in a single with statement: 


with RecName1, RecName2, RecName3 do 
begin 
Fieldl := Vary; { belongs to RecName1 } 
VarX s= Field2; { belongs to RecName2 } 
Field3 := VarzZ; { belongs to RecName3 } 
end; 
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Of course, this multiple usage requires that the field names in the record or 
object types are all distinct, that is, the same field name does not appear more than 
once. 

The with statement will appear further with record structures and, in later 
chapters, with objects. 

The example program DataTest.PAS uses the with statement both to read data 
field entries through a subroutine and to pass information to the subroutine, thus: 


with Entry do 


begin 
Name = ReadData( 'Name', sizeof€ Name ) ); 
Company := ReadData( 'Company', sizeof( Company ) ); 


end; { with } 

The comment { with } following the closing end statement is provided simply 
as a matching reference, indicating the corresponding opening statement. Its pres- 
ence or absence does not affect the program code. 


The alternative to using the with statement would be to fully-qualify all 
references: 


Entry.Name := ReadData( 'Name', sizeof( Entry.Name ) ); 
Entry.Company := ReadData( 'Company', 
sizeof(€ Entry.Company ) ); 


This is also perfectly valid, though it does require more work by the program- 
mer, who must type fully qualified names. 

A second example of the with statement is used after reading the data entries 
to write a report back to the screen showing the entries. 


with Entry do 


begin 
writeln( Name, ' ', Company ); 
writeln( Address, ' Bo aE ag) Re ey eS ee ys 
write 'C', Area, ') ", Phone ); 
if Ext <> '' then writeln( ' Ext: *, Ext 2; 


end; { record } 
It produces a formatted display: 


John Smith Amalgamated Limited 
1234 5th Avenue Anywhere, CA 99999-9999 
(555) 555-1234 Ext: 789 
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As you may expect at this point, the with statement may be used whenever 
practical, simply to save laborious keyboard entry while writing programs. The use 
or absence of the with statement does not affect the size of the compiled program. 


Getting the Data 


Data input can take a variety of forms, but in most cases, begins with a keyboard 
entry. For string data, which we are using in the present example, the readIn 
function is the usual choice. But simply waiting for the user to type the appropriate 
string response is rather awkward. A good program provides at least a minimal 
prompt. 

The best way to prompt for input for multiple fields is to make the display look 
as polished as possible, which can involve varying degrees of elaboration. In this 
case, the function ReadData is called with two parameters: a prompt string and an 
integer indicating the expected string length. 


Name := ReadData( 'Name', sizeof( Name ) p 


The second parameter is provided automatically by calling the sizeof function 
to return the size of the field. 
function ReadData( Prompt: string; Size: integer ): string; 
var 

1, X, yY 3: integer; 
EntryStr : string; 
begin 
dec( Size ); 
writeC Prompt:10,. "sr. % >) 

Here, the ReadData function uses a width specification to right-align the 
Prompt strings for all entry requests. In later examples, however, an input screen 
window will be designed, using a different input alignment. 

Next, the ReadData function saves the current screen position in the x and y 
variables, then writes a string of underscores to show the user how long an entry 
may be made. 


xX := Wherex; 
y := WhereyY; 
for) 8° 1540 Sige doe wrivet pe lees Ie. 


GOTOKY.  Byiw) 3 
rPeadint Entrystr ).; 


Then the cursor is repositioned at the saved location, and the readIn procedure 
is called with the local string variable EntryStr. 
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Since EntryStr is defined as a string with a length of 255 characters, the user is 
not restricted in any fashion, and could easily type an entry that exceeds the 
expected, allowable length. This is the reason for the underscores following the 
prompt. Also because of this, the subroutine is provided with instructions, after the 
string entry is complete, to reposition the cursor, erase to the end of the line, truncate 
the entry to the allowed length and rewrite it. 


EntryStr := copy( EntryStr, 1, Size i { truncate entry } 
gotoxy( x, y %; clreot; 
writeln( EntryStr ); 
ReadData := EntryStr; 
end; 


The local variable EntryStr has already been truncated to the desired length 
before it is returned, but this really isn’t necessary for the program, because the 
assignment, which is made in the main program, automatically truncates any string 
too long to fit. 

A data entry session might produce a display looking something like this: 


Name: John Smith 
Company: Amalgamated Limited 
Address: 1234 5th Avenue 
City: Anywhere 
State: CA 
Zip Code: 99999-9997 
Area Code: 555 
Phone: 555-1234 
Extension: 789 


The program DataTest.PAS will be extended in later chapters to 1) include a 
data file, 2) print an address list, and 3) implement a simple phone dialer through 
a modem. But, for the moment, we will turn to other variations of data structures. 


Mixed Data Structures 


The DataTest example used only string data but data structures may and do include 
all types of data. The next example shows a simple accounting record, suchas might 
be used in a checkbook program. This data structure includes integer, real and 
string fields, as well as another custom data field, the date record. This is illustrated 
in the example program Check.PAS at the end of this chapter. 

Before we define the new data structure, we must define the date record type, 
DateRec: 
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type 
DateRec = record 
Day, Month, Year : byte; 
end; 


Since day and month values never exceed two digits, a byte-sized record is large 
enough, and if the century is ignored, the year can be stored as a byte as well. 
With the DateRec type defined, we can define the CheckRec type: 


CheckRec = record 
CkDate : DateRec; 
CkNum : word; 
PaidTo : stringl20]; 
Amount : real; 
Comment : stringl60] 
end; 


Since check numbers are customarily unsigned, a word value provides ample 
space for numbers up to 65,353. At the same time, since this is not designed for the 
national budget, a real value for the Amount field provides a minimum of 11 
significant digits, which should be more than ample, even allowing for inflation. 

For a real checkbook program, however, a minimum of one further record type 
would be required to handle deposits, and realistically, the program should also 
handle bank service charges, and so on. 

Is the next step, then, to create one or more new record types? 


Variant Record Types 


A variant record type is a record that has more than one structural format with a 
type field specifying which format is being used for each specific record instance. 
As an example, for the checkbook program, we can define the variant record types 
as Debit (checks), Credit (deposits) and Other (special entries such as bank fees and 
interest earned). 

Before defining the record variations, we’ll define a variation type as Transac- 
tion: 


type 
Transaction = (€ Null1, Debit, Credit, Other + Be 


To later specify the Other types, we define a second type: 


Special = ( Null2, Overdraft, Service, Interest, Adjust ); 
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Note that Transaction and Special include the type instances Null] and Null2. 
These are included for use as defaults in the selection process—to be used until a 
correct selection has been made. A separate default name has been defined for each 
type, however, rather than simply using Null for both, because Pascal does not 
allow duplicate names in type definitions. 

Aside from nulls, the remainder of the type names should be self-explanatory. 

The DateRec definition is the same as in Check.PAS: 


DateRec = record 
Day, Month, Year : byte; 
end; 


Now we're ready to define the record type, TransAct: 


TransAct = record { transaction record } 
Cleared : boolean, 
TransDate : DateRec; 
Comment : stringl60]; 
Amount : real; 


The first four record elements are simple. Three of these are simply repeated 
from the earlier CheckRec definition. The new entry, Cleared, is a simple boolean 
record, to be used later when reconciling the data entries with the bank statements. 

The first four fields are common to all record entries, but now we come to the 
variant record structure, which is defined using a case statement: 


case Action : Transaction of 
Debit a’ CkNum : word; 
PaidTo : stringl20] 12 
Credit : ( { no special record type } ); 
Other - (€ Itemtype : Special ce: 


end; { record } 


Using a case statement in a record is a bit different than using a case statement 
within a procedure. 

First, the case selector Action : Transaction is defined as a record element within 
the case..of statement, but is not defined elsewhere as a record element. 

Second, each case instance is followed by parentheses enclosing the record 
elements defined for this specific case type. Previously, when case selections were 
executed, if more than one statement appeared in a case instance, the begin..end 
delimiters were used; within a record definition, parentheses serve the same 
purpose. 
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Third, the Credit instance does not have any special record elements defined but, 
if included, still requires an empty parentheses. It could have been omitted entirely. 

Fourth, within the record definition, the case delimiter statement does not have 
a matching end statement. The end statement that does appear matches the record 
statement. This is also the reason that the variant field definition must appear last 
in the record definition and cannot be followed by other field definitions. 

Figure 9-1 shows examples of the three variant record structures defined by 
TransAct. In memory or in a record file, all records are the same size regardless of 
the variant structure. This is true even though, as shown in the examples, some 
variants may not fill the allocated space. Of course, the string field within the 
records may also have empty space when the string entry is smaller than the record 
field allocated. 

As an alternative, it is possible to create packed records for files where no 
wasted space is tolerated, but this type of record is slower to access and not as easily 
manipulated. Therefore, for the present, we will ignore packed record types. If your 
application does depend on large data files, and space is critical both in memory 
and in the storage media, the Paradox database engine provides a useful alterna- 
tive. It is available as an interface for Pascal programs. 

For most applications, however, the theoretical savings in space using packed 
records is more than offset by the difficulty in access and handling. 


Figure 9-1; Variant Record Examples 
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Using Complex Data Types as Parameters 


Functions in Pascal can return only simple data types, but it is possible to pass a 
complex data type as a variable parameter to a procedure, which then returns the 
complex data structure with new values (data). The ReadDate procedure in 
Check.PAS or Check2.PAS illustrates this principal using a record structure of type 
DateRec. 

The calling format for ReadDate is defined as: 


procedure ReadDate( XPos, YPos: integer, 
var Date: DateRec ); 


In the example, ReadDate is called as: 
ReadDate( 20, 2, TransDate ); 


The TransDate parameter is a field within the TransAct record. 

Normally, when a subprocedure is called and the calling routine passes a local 
(or global) variable as a parameter, the called procedure receives the data contained 
in the variable, but creates its own local copy of the variable completely indepen- 
dent of the original. In this fashion, the new local variable can be changed without 
affecting the original in any fashion. 

In this case, however, the ReadDate procedure receives the calling parameter 
as a variable parameter, as designated by the var keyword. Also, in this case, 
ReadDate receives the address of the TransDate structure belonging to the calling 
routine, but does not create a local copy, even though the original data structure 
does use a new name local to the ReadDate procedure. 

Remember, witha variable parameter, the variable used as a parameter remains 
the same variable even though it is temporarily using a new name. The corollary 
of this is that constant values can never be passed as variable parameters; they can 
only be passed as values. 

Therefore, when ReadDate plugs new values into the structure that was passed 
as a variable parameter, the information is being written to the original structure, 
not to a local copy. When the called procedure terminates, this new information is 
available to the calling routine. 

Since the variable parameter in this instance is, itself, a record structure, the 
local name used by the local procedure is required to access the record fields, thus: 


with Date do 


repeat 
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Month := ReadWord( XPos, YPos, 'Month', 0, 2 ); 
UnER UC Menth tn o1.6129 7: 


It is not necessary, however, to use the record designation for the larger record 
structure, TransAct, which Date is a part of. The purpose of the reference to Date is 
to tell the compiler how the fields within the DateRec structure are organized. Since 
the local procedure already has the address of this part of the structure, what is 
needed here is simply enough information to decide how each of the fields within 
this part of the structure is organized. 

It would also be possible to provide all of this information as addresses by 
saying that Month is located at the Date address plus one byte, and is one byte in 
length, while Day is at the Data address itself, but is also one byte in length, and, 
last, that Year is located at Date+2, and is also one byte in size. However, the point 
here is simplicity. Reference by name and structure type is certainly simpler and 
easier. If you understand how to refer to record fields by their labels, then you don’t 
need to worry about how to reference to these by address. 


An Array of Constants 


As part of the ReadDate procedure, we can provide a simple form of error trapping 
by defining a constant array titled Limit, which contains the maximum number of 
days that are valid for each month: 


const 
Limit cceeraxvst 1.124. of: byte) 
wie eee wtp ey whe BOP eae ee BO 84 SO See 
We have defined the array with index values from 1 to 12 to correspond to the 
expected month values, and since no values larger than byte-sized will be used and 
no signed values are required, this array requires only 12 bytes of data. 
Using this array of data is very simple: 


repeat 
Day <= ReadWord( TPos, YPos, "Day', 0, 2 ); 
uNntTICe Bay tn £4. Limi tChonth3. |): 

The reference [1..Limit[Month]] is slightly unusual usage, but, nonetheless, is 
perfectly valid. It allows the until statement to test for a result in the range 1 to 
Limit| Month] by asking if Day belongs to the set, instead of executing two separate 
tests for upper and lower limits. 
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We have not, however, made any provision for checking to see if February 29th 
is valid—i.e. if this year is a leap year. This provision might be worth adding in a 
serious application, but, we would have to remember that 1900 is not a leap year, 
while the year 2000 is. 


Summary 


Record structures provide a means of organizing mixed data, making it easy to 
manipulate collections consisting of several individual types and data elements. 
Two examples have been shown, a data structure for an address/phone file and a 
data structure for a checkbook program, but data structures can be created for 
anything. 

The checkbook data structure will be used again in several further examples, 
and will finally be developed into a complete application incorporating a 
windowed display, scrollable lists of transactions and files of data. 

However, beginning by introducing a complete program with all of these 
features would be too complex to show what, why and how the various features 
were being created. Therefore, we will add features one step at a time, not all at 
once. Of course, you are always free to adapt and change the organization and 
structure of the program, or the data itself, to suit your own requirements. 

The listings for the demo programs DataTest.PAS, Check.PAS and Check2.PAS 
appear in the following pages. They provide very basic input handling for the data 
fields and structures illustrated, but also illustrate a constant array definition in the 
ReadDate procedure. 


{ DataTest.PAS } 
{ demonstrates entry to } 
{ data structure fields } 


{ssSeeeseesrocsssessseseresas} 
uses Crt; 
type 
AddData = record 

Name » stringi sua; Company : stringl201; 
Address : stringl201]; ETty¥ : g¢tringl15]>; 
State : etringilzi Zip * strifngaetlt0 J ; 
Area 2 Stringtsis; Phone . strinetéi; 
Ext * stringl5J; 


end; ff record } 
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var 
Entry :s> AddData; 


function ReadData( Prompt: string; Size: integer ): string; 
var 

Vg ye oe : integer; 

EntHrYStr os string: 


begin 
dec’ Size): 
for i 3:3 10 downto ord( PromptCO] ) do write( ' ' ); 
Wretet Prenat... bs Fy 


7 
xX := WhereX; y := WhereY; 
TOR Psa eto; Size: do write hy heyy 
gOtORYI x5. ¥ =D: 
resaqtint -Entrystr. 3; 
EnNtryorr. 3= copy EntryStr, 1, Size. ?: 
{ add to truncate entry } 
GOCGOKVE xX, y J5 setrpeots 
writeln(€ EntryStr )>; 
ReadData := EntryStr; 
end; 


begin 
cingers 
writeln(€ 'Memo: Entry requires ', 
Si2eOTe Entry. 275 betes. to 3: 
writeln; 
with Entry do 


begin ie 
Name >= ReadData( 'Name', sizeof( Name ) ); 
Company := ReadData( 'Company', sizeof ( Company ) ); 
Address := ReadData( ‘Address', sizeof( Address ) ); 
Cay ty = ReadData( 'City', Sizeoct< Crty >). 22 
State = ReadData( 'State', Sizeott: State.) )s 
Zip = ReadData( 'Zip Code', Sitzgeott 23p:2-0'3 
Area = ReadData( ‘Area Code', sizeof( Area ) ); 
Phone = ReadData( 'Phone', sizeof( Phone )-); 
Ext = ReadDatat ‘Extension’, sizeof€ Ext ) ); 


end; { record } 
writeln; 
with Entry do 


begin 
writeln(€ Name, ' ', Company 22 
wreiteln( Address, ‘ Leese ee ee eR Rae ye 


WEURCA Ut, Atea;, 82) yy Peate 32 





it Ext ae * 
end; {< with } 
readln; 

end. 


then writetnc ° 
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Extz*2 Bet (23 


{ Check.PAS } 
{ a mixed data record } 


uses Crt; 


type 
DateRec = record 
Day, Month, Year 
end; 
CheckRec = 
CkDate 
CkNum : 
Amount : 
PaidTo 
Comment 
end; 


byte; 


record 

: DateRec; 
word; 

real; 
stringleol; 
stringl60] 


var 
Check CheckRec; 
function ReadData( XPos, YPos: 
Prompt s 
Size: 
var 
1, Xs, Y 
Entrystr 
begin 
gotoxy( XPos, 
dect Size 2; 
writet Prometirtg, te *' 2; 
x := Wherex; 
y := WhereY; 
for 
gotoxy( xX, ¥ 2 
readln( EntryStr ); 
EntryStr := copy( EntryStr, 
gotoxy€ x, y J}; ct req; 
writetn( EntrySsStr 0; 


integer; 
strings; 


YPos ); 


1 #:= 


1 to Size do write( 


1, 


integer; 
string; 


integer )2 string; 


28 pie 


S28 Ry 
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ReadData 
end; 


function ReadWord( XPos, 


word; 

var 
VStr 
Result 

begin 
gotoxy( XPos, 
write( Prompt, ': 
XPos Wherex; 
repeat 

gotoxy( XPos, 


string: 


integer; 


ENE ryYStrs 


YPos: 
Value: 


integer; 
word; 


Prompt: 
STzZes 


string? 
integer ): 


YPOs:) 5 


i] ry 


YPoOs: 2? 


re@oin( Vstr..>; 


VOLS VStr, 
gotoxy( XPos, 


Value, 


Resutt:):: 
YPos@ i}: 


write( Value:Size ); 


until Result = Q; 
ReadWord := Value; 
end; 


procedure ReadDate( XPos, YPos: integer; 
var Date: DateRec ); 
const 
Limit arraylt. «124 of B¥ te: = 
phe ee pS Ty SUp Sls Se eee eae ay SAb sO a4 s SE 
var 
TPos integer; 
begin 
with Date do 
begin 
gotoxy( XPos, YPos ); 
wPrvtet: (pater * dz 
XPos := WhereXx; 
repeat 
Month := ReadWord( XPos, YRos, ‘*Month'; 0, 2 ); 
Untitt Month -1n £1... 1723.94 
gotoxy( APos, YPos ); clreol; 
Wie tes: Monthy 82% Jy 
TPos := WhereX+2; 
repeat 
Day := ReadWord( ‘TPos, |¥YPes, ‘Day’, 0, 2°); 


until Day in 
gotoxy( XPos, 


Ltn tinonenad .)}3 
YPos 27 et reots 


write€ Month, ‘'/', Day, 


TPos := WhereX+2; 
repeat 
Year := ReadWord( TPos, YPos, ‘'Year', O, 
untilt Yeer mofo. ssa" 7 
gotoxy( XPos, YPos ); clreol; 
writet Month, '/*, Bay, "7s, Year 3; 
end; 
end; 
procedure ReadReal( XPos, YPos integer; 
Prompt string; 
var Value real ); 
const 
Size = 11; 
var 
VStr string: 
Result integer; 
begin 
Value := Q; 
str( Value:Size:2, VStr ); 
gotoxy( XPos, YPos ); 
write( Prompt, ‘': ' )-; 
XPos := WhereXx; 
repeat 
gotoxy( XPos, YPos ); 
readln( VStr ); 
val( vStr, Value, Result ); 
gotoxy( XPos, YPos 2; clreol; 
write( VStr ); 
until Result = O; 
end; 
begin 
6. FS6r 7 
with Check do 
begin 
CkNum := Q; 
CkNum := ReadWord( 2, 2, 'CheckNum', CkNum, 
ReadDate( 20, 2, CkDate ); 
ReadReal( 2, 3, '‘Amount', Amount ); 


PaidTo := ReadData( 2, 


4, 
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1/! as 


“Peid-to*, 


sizeof( PaidtTo ) ); 


Comment := ReadData( 2, 


D+ 


'Comment', 


sizeof(€ Comment ) ); 


writeln; writeln; 


a F- 


5 Re 
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write ‘Check Numbers), CkNum:)» 
with CkDate do 
writetnt.* Date pi MORtH ys Bay, hl, fear) s 
writeln(€ ' Amount: $', Amount:5:2, 
' Fated: tot, Patete 2s 
writeln(€ 'Comment: ', Comment ); 
writeln; 
ends (<° e7th > 


readln; 
end. 
(ssS=S2sese8e55s5s=2s====} 
{ Check2.PAS } 
{ amixed data record } 
(=SssSsSs2See25222=22====} 
uses Crt; 
type 
Transaction = ( Null1, Debit, Credit, Other re 
Special = (€ Null2, Overdraft, Service, Interest, Adjust.) 
DateRec = record 
Day, Month, Year : byte; 
end; 
TransAct = record { transaction record } 


Cleared : boolean; 
TransDate : DateRec; 
Comment : stringl60]; 
Amount : real; 
case Action : Transaction of 


Debit ae CkNum : word; 

Patato: 2 etringt201: 3 
Credit =: € € no special record type } ); 
Other : € Itemtype : Special ds 


end; { record } 


var 
Entry <¢ TransAct; 

procedure Beep; 

begin 
Sound (220); delay (100); 
Sound (440); delay (100); 
NoSound; 

end; 


function ReadData( XPos, YPos: integer; 
Prompt: string: 
Size: integer ): string; 


var 
1a’ Re ¥ integer; 
Entrystr string; 
begin 


gotoxy( XPos, 
dec(€ Size ); 


YPos ); 


wreitet Promet:10, "s * 2; 

x := WhereXx; 

y := WhereY; 

for i := 1 to Size do write( 


dotoxy€ x, ¥ 23 

readln( EntryStr ); 
Entrystr copy( EntryStr, 
gotoxy< x, y 27 Clreol; 
writeln( EntryStr ); 


ReadData := EntryStr; 
end; 
function ReadWord( XPos, YPos: 
Value: 
word; 
var 
VStr string; 
Result integer; 
begin 
gotoxy( XPos, YPos ); 
write€ Prompt, ‘'! * dF 
XPos := Wherex,; 
repeat 
gotoxy( XPos, YPos ); 
readln( VStr J); 
val( vStr, Value, Result 


if Result <> 0 then Beep; 
gotoxy( XPos, YPos ); 
write€ Value:Size ); 


until Result = O; 
ReadWord := Value; 
end; 


procedure ReadDate( XPos, YPos: 
var Date: 


const 
Limit array[1..12JjJ of byte 
€ 31, 29% S31, 30, 312 345 
var 
TPos integer; 
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); 


1, S128 22 


integer; Prompts: string; 
word; Size: integer ): 
); 

integer; 

DateRec ); 

a1 SAG et op oO,’ ST 2} 
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begin 
with Date do 
begin 
gotoxy( XPos, YPos ); 
writet "Date: ° )s 
XPos := Wherex; 
repeat 
Month := ReadWord< XPos, YPos, ‘Month', 0, 2 ); 
UAT SUG: Month: tn €4...123' 0) 
gotoxy( XPos, YPos ); clreol; 
Ur Teel Month, Fe" Py 
TPos := WhereX+2; 
repeat 
Day := ReadWord( TPos, YPos, ‘Day', 
until€ Day in C€1..LimitC€MonthI] ); 
gotoxy( XPos, YPos ); clreol; 
WETTER Month, 7), Bay, lt Oe 
TPos := WhereX+2; 
repeat 
Year := ReadWord( TPos, YPos, 'Year' 
untiL( Year: in CO. .997 5)» 
gotoxy( XPos, YPos ); clreol; 
WPUCes Month, 4", bay, (7 ty Year Je 
end; 
end; 


procedure ReadReal( XPos, YPos : integer; 
Prompt : string; 
var Value’: Preal: ); 
const 
Size = 113 
var 
VST: =e “String: 
Result : integer; 
begin 
Value := Q; 
Stren oVatue: Size:2,  ¥Str ) > 
gotoxyt A3Pos, Y¥ros 2:3 
WHTTEL Promet, 8) feds 
XPos := WhereXx; 
repeat 
gotoxy( XPos, YPos ); 
readin V$Ster 22 
val( vStr, Value, Result ); 
if Result <> 0 then Beep; 
gotoxy( XPos, YPos ); clreol; 


ee ae Fe 


gy 293 





write¢ VStr 33 
until Result = Q; 
end; 
function SelectAction : Transaction; 
var 
Tact 3: Transaction: 
Ch £ char: 
begin 
repeat 3 
GOtou yes 7-33 CE PEOL: 
write(€ "Select entry type ', 
'(<C>heck, <D>eposit, <O>ther): ' ); 
Ch := readkey; 
case upcase( Ch ) of 


‘C" : TAct := Debits 'D* : TAct z= Credit: 
"O" : TAct := Other; 
else 
begin TAct := NuLllt; 
Beep; end; 


end; {case} 
unti.| TAet <= -RElLtT> 
gotoxy( 1, 4 3 ¢€l reat: 
SelectAction := TAct; 
end; 


function SelectOther : Special; 
var 
1HCt. § Soeciats 
cn © ener: 
begin 
repeat 
gotoxy< 34.41.2793 
write(€ "Select type (<A>djustment, <I>nterest, ', 
'"<O>verdraft, <S>ervice charges): ' ); 
Ch := readkey; 
case upcase( Ch ) of 


rA* © Facet := Adidusts "I" « TASte t@:. laterest; 
"OO" ss TACt := Overdraft: "Ss" §. TAGt. ee. tervice: 
else 
begin TAct := Null2; 

Beep; end; 


end; {case} 
UTIL TAG <> Nwiles 
SOtoxrys: Fs. 2°22 clreot: 
SelectOther := TAct; 
end; 
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begin 
clPrect? 
with Entry do 
begin 
Cleared := False; 
ReadDate( 2, 3, TransDate ); 
Action := SelectAction; 
case Action. of 
Debit begin 
CkNum := ReadWord( 20, 3, 'CheckNum', 
GChkhlum, «$23 
PaddTo := ReaddData(: 20, 4,- "Paid to’, 
gsizged?t:Paidto-} 2; 
end; 
Chegy?t-& 2 
Other Itemtype := SelectOther; 
end; {case} 
ReadReal( 2, 5, ‘Amount’, Amount ); 
Comment := ReadData( 2, 6, 'Comment', 
sizeof( Comment ) ); 
end: €:-07th:2 
writeln; writeln; 
with Entry do 
begin 
case Action of 
Debit write( 'Check Number: ‘, CkNum ); 
Credit write( "Deposit: pias SS 
Other case Itemtype of 
Adjust £ wettet “Adjvustment..' 27 
Interest write( ‘Interest earned ' ); 
Overdraft writet Overdraft °°); 
Service write( 'Service charges ' ); 
end; {case} 
end; {case} 
with TransDate do 
writeln¢ ' Date: "> Wentns *7*;. Bay, Cl >: Year: 3; 
wrietet: ' Amounts: S$, Amountis:2 2; 
if Action = Debit then writetn(:' Paid tor. '3 Petdto :) 


else writeln; 
writeln( ‘Comment: '‘, Comment ); 
writeln; 
end: © Aer tn 3? 
readln; 


end. 


Chapter 10 


Streams, Files, and Device I/O 


Creating data structures and writing data entry handling are central to the pro- 
gramming process, but, we also need to be able to save the data for reuse. This 
chapter explains how Turbo Pascal handles files and how to create them. 

To the computer, all files are simply sequences of bytes. It is the DOS operating 
system that is expected to keep track of the location and size of each file, and any 
details about the file such as read-only flags, and so on. 

To the programmer, computer files come in several different types. This is not 
because there is any physical difference from one file to another—any file can be 
handled any way desired—but because applying different types of special handling 
makes access and storage easier. 


Pascal File Types 


Pascal supports three principal file types: typed, text and untyped. 

Of these three, the simplest file type is the untyped file. This is a low-level I/O 
channel used for direct access to any disk file, ignoring type and structuring. An 
untyped file is declared with the word file without specifying a file type, thus: 


var 
BYteritie 3b Tt te: 


An untyped file would be used primarily to access unstructured information 
or to duplicate large blocks of data by copying from one location to another. 
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The second file type, the text file, is expected to be a file of text information 
consisting of lines terminated by carriage return characters (ODh) and, optionally, 
line feed characters (OAh). A text file is declared quite simply as: 


var 
FExtrree—s-texts 


Note: A text file is not the same as a file of char. 
The third file type is the typed file. It consists of one or more entries of a specified 
data type, which may be a simple or complex data type. A typed file is declared as: 


var 
Byte@Fite <2: fite of byte; 
Chearisite: =. tile of char; 
DataFile : file of DataRec; 
BankFile : file of TransAct; 


File /O 


The term file suggests a disk file written to or read from a floppy disk or hard drive, 
and much of the time, this is precisely what a file is used for. Technically, however, 
a file is actually an input or output channel the program uses to communicate to 
an external device, such as a floppy or hard drive video display, keyboard, serial 
or parallel port, or some other specialized device where information is written or 
read. 

For the present, most file operations will be demonstrated as disk file opera- 
tions, but please keep in mind that later, a different type of file will be demonstrated. 


Opening a Text File for Input 


The first step in opening a file is to declare a file variable by defining a file type, as 
shown above. 

The second step is to associate the file variable with an external file via the 
Assign procedure. In the case of a disk file, this is done by associating the file 
variable with a filename as follows: 


var 
TextPite + text: 
begin 
assign( TextFile, FileName ); 
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The filename can be a string variable or a constant string, and may consist 
simply of the name and extension of the file, or a fully qualified drive, path and 
filename specification such as “D:\ DIRPATH\SUBDIR\FILENAME.EXT”. 

For a fully qualified filename, the only restrictions are those imposed by DOS: 
a maximum drive/path length of 67 characters, a maximum file name length of 
eight characters and an extension length of three characters. 

The next step depends on whether the named file is an existing file or a new 
file just being created. 

If you are opening an existing file, you call the Reset procedure, thus: 


{$I-} reset( TextFile ); {$I+} 


Reset opens the file, positioning the file pointer to the beginning of the file. The 
alternative, opening a text file for output using the rewrite procedure, will be shown 
in a moment. 

A text file opened with reset is opened as a “read-only” file, while the rewrite 
instruction opens the file as a “write-only” file. Typed and untyped files, however, 
are always opened as “read/write” regardless of whether the reset or rewrite 
procedure is used to open the file. 


Error Checking 


Any time physical (disk) files are being opened, it’s a good idea to include your 
own error checking and handling rather than depending on Pascal or DOS to report 
any errors. This is primarily because, if you do your own error checking, your 
program can recover from the error, whereas if the error is handled by Turbo 
Pascal's default error procedures, your program is terminated abruptly. 

The {$I-} statement preceding the reset command is a flag instruction to turn 
error checking off. The {$1+} statement following tells the compiler that the program 
should resume normal error checking. In this fashion, any error resulting from the 
reset command does not cause the program to terminate execution. 

If an error does occur, an error flag is still present in the system and needs to 
be handled. 

Turbo Pascal provides an I/O error reporting function, [OResult, which returns 
an integer error code if an error occurs or returns zero if no error occurs. A simple 
boolean comparison provides your own error reporting, thus: 


if I10Result <> O then 
report the error here 
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The actual value returned by [OResult, when a run-time error occurs, will be a 
integer value (error numbers 100..106). Corresponding error messages and expla- 
nations can be found in Appendix A of the Turbo Pascal Programmer’s Guide. The 
most common error, of course, is simply that the file cannot be found, usually 
because an incorrect path or filename was supplied or because the file does not 
exist. 


Opening a Text File for Output 


As with the input file, the first step to opening an output file is declaring a file 
variable by defining a file type: 


assign( OutText, FileName2 ); 
rewrite OutText ); 


It is the second step that establishes this file as an output file, using the rewrite 
statement. 

If a file with the specified filename already exists, the rewrite statement trun- 
cates the existing file to a length of zero, discarding any information that might 
already be stored. If no such file exists, a new file is created with the specified name. 

In either case, the file pointer is set to the beginning of the file, and the empty 
file is ready for new information to be written. 

Remember that for text files, the file status following Rewrite is ““write-only”, 
while for typed or untyped files, the file status is always “read/write”. In this 
example, however, before anything can be written to the output file, the input file 
has to be read. 


Reading the Input File 


In this example, the text file has been opened using the reset command, which gives 
the file a read-only status. Therefore, nothing can be written to it. Reading the file 
contents, however, is quite simple, requiring only a simple while..do loop. 
while not EOFC TextFile ) do 
begin 

readln(€ TextFile, TextLine ); 

In this case, the while..do loop is a while not..do loop, but the function is the 
same: the loop repeats until the EOF function returns True, indicating that the end 
of the file has been reached. As long as the file pointer has not reached the end of 
the file, the EOF function will return False, allowing the loop to continue. 
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Notice also that the readIn procedure used here is different from earlier exam- 
ples, because this usage includes a file variable specification, TextFile. 

In previous examples, the readfile procedure has been used in two forms: first 
as ReadIn; which simply waited for the Enter key to be pressed and, second, as 
readIn( StrVar );, which also waited for a terminating Enter key but returned all 
preceding keystrokes in the string variable. 

In this example, however, the file variable parameter instructs the readIn 
procedure to accept input from the indicated file, which it does by reading charac- 
ters into the string variable until a terminating carriage return character (ODh) is 
found. If the carriage return character is followed by a line feed character (OAh), 
this character will also be read from the file, but neither is returned as a part of the 
string. 

A fourth form is also possible, in which the source parameter indicates a serial 
or parallel port or the console device (CON:), which, for input, is the same as the 
keyboard and is assumed by default in the earlier examples. 


Writing the Output File 


Like the readIn procedure, the writeln procedure can also be used with a file 
variable specification, directing output to a file instead of the console (video): 


writeln( TextOut, TextLine ); 


In the example Read Text.PAS, at the end of this chapter, both the readIn and 
writeln statements appear within a single loop block so that each line read from the 
input file is then written to the output file, ending only when there is nothing left 
in the input file to read. 

We've mentioned that the readIn procedure can be used with a device specifi- 
cation as well as a file specification, the same is even more often true of the writeln 
procedure. Pascal has several predefined file handles that refer to [/O devices such 
as LST or PRN for the printer output, and writeln is often called like this: 


writeln( PRN, TextLine ); 


This example sends the output to the printer port. These file handles will be 
covered further under the heading “Predefined Streams,” but for now, just note 
that they do not need to be opened using the assign and reset or rewrite statements, 
nor closed using the close statement. 
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Closing Files 
Any time a disk file has been opened, it should also be explicitly closed: 


closet Textout =); 
close( TextFile ); 


Any files still open when a program terminates may or may not be completely 
updated, but the close instruction ensures that the file is accurately updated and the 
DOS file handle released for reuse. 

In Chapter 1, after completing the Turbo Pascal installation, you were 
instructed to include the statement FILES = 20 in the Config.Sys file. DOS sets a 
default value for files of 8, allowing eight file handles to be active at any time. But 
this does not necessarily mean eight disk files, because other system devices also 
use file handles for communications. Thus, setting 20 file handles as a minimum 
provides ample file handles for any except very badly behaved applications or, 
possibly, a large number of active TSRs. Closing files that are not in use is one 
difference between a well behaved and a badly behaved program. 


Appending Text Files 


For output files that are being intermittently updated, the append procedure makes 
it easy to create well behaved files. Once a file variable has been opened with assign, 
reset or rewrite, and then later closed, you can use the append instruction with the 
established file variable to reopen the file as write-only, with the file pointer set at 
the end, ready for new material to be added. For example: 


append( TextOut ); 


In the preceding example, the TextOut file could have new material written at 
any time by calling the append procedure to reopen the file and then calling writeln 
as before. Material could also be added to the TextFile file, which was originally 
opened as a read-only file, in the same fashion. 

Of course, files reopened with append do need to be explicitly closed again. 

Note: The append procedure is valid only with files of type text. Adding 
material to typed or untyped files requires other procedures, which will be dem- 
onstrated presently. 
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Untyped File Operations 


Untyped files provide low-level access to any type of disk file without regard to the 
actual file type or structure. This type of access is commonly used to copy blocks 
of data to or from a program, or to copy entire files, usually employing the 
BlockRead and BlockWrite procedures. 

The CpyBlock.PAS program at the end of this chapter demonstrates these two 
procedures by treating the source code for this program as an untyped file and 
copying the contents under a new filename. 

For an untyped file, the reset and rewrite procedures are normally called with 
an additional, optional parameter specifying the record size to use when transfer- 
ring the files being opened. 


peset( infite, 2-34 
rewrite Outk?1e, 352% 


If the record size parameter (1 in the examples above) is omitted, a default 
record size of 128 bytes is assumed. This value dates from historical circumstances 
when all files, of any type, were always some multiple of 128 bytes in size. Today, 
however, this quantum sizing no longer applies. Therefore, for untyped files, a 
record size of one is normally specified. This ensures that, regardless of the actual 
file size, no partial records will occur on read or write. 

To use the blockread and blockwrite procedures, a data buffer is also required. 
For this example, the buffer is declared with a size of 128 bytes: 


Buffer +: arreyit.. te6) of Byte: 


Here, however, the size of the array is not critical, as long as it is some multiple 
of the declared record size. The size used in this example is for demonstration 
purposes only. For an actual application, a larger size, such as 1K (1024 bytes) or 
greater, would provide faster operations by transferring larger blocks of informa- 
tion in each step. | 

After the two files—input and output—have been opened, the blockread and 
blockwrite procedures are used to read and write blocks of information without 
regard to text line lengths or even what type of information is being copied: 


repeat 
BlockRead( InFile, Buffer, BufSize, Count : 
BlockWrite( OutFile, Buffer, Count, Result d; 
until (¢. Gomnt <> @ufsi 26.2 Gr 4 Result.:<> Count ); 
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The Buffer variable is the array used to hold the data read and written, while 
the variable BufSize has been established as 128 (the size of the array). This tells 
blockread how many records should be read from InFile. 

Itis the Count variable, however, that returns with the actual number of records 
read from the input file. This information is passed, in turn, to the blockwrite 
procedure to control how many records are written to the output file. Remember, 
each record is one byte in size. 

In the blockwrite procedure, the Result variable should return the same value 
passed by Count, indicating that the appropriate number of records were actually 
written. If not, an error probably occurred, most likely because no space was 
available on the output media. This comparison, however, is one of the tests used 
to determine when the copy loop should terminate. 

The control loop for this copy process is written as: 


repeat 
. { read and write blocks } 
until Ceeat:' «> BuTsice 2ior: CC: Result: s> Count: 2; 


Two tests are used to determine how long this process should continue. The 
first test, Count <> BufSize, is looking for the blockread procedure to find less than 
BufSize records remaining in the source file, as reported by Count, which is showing 
the actual number of records read in. When this happens, the end of the file must 
have been reached, and there’s no point in going further. 

The second test, indicating that the output media is filled, has already been 
described above. 

No other error testing is executed. Since this process operates independently 
of the type of data in the file, there really isn’t any error checking that is appropriate, 
aside from ensuring that everything in the source file is copied to the output file. 

The demo program CpyBlock.PAS adds a test feature that, while the blocks are 
being copied, echoes the contents of these blocks to the screen. Before echoing each 
block, it writes the variable Count as <nnn> in a contrasting color, showing where 
each block begins and how many records were found on each loop. 

Figure 10-1 shows a sample screen generated by CpyBlock, where the final 
block copied is only <83> records, indicating that the end of the input file has been 
reached. 


Chapter 10: Streams, Files, and Device I/O 157 


Figure 10-1: Screen Display Showing BlockRead and Block Write Operation 


writeln(€ ’The file ’, InFileName, ’ can not be found?’ ); 
<126> Sound( 226 ); delay ( 166 ); 

Sound( 446 ); delay 168 ); 

NoSound; 
end else 
begin 

assign( OutF i le, OutFileName ); 

rewrite( OutFile, 1 ); 

repeat 

BlockRead ¢ InFile, Buffer, BufSize, Count 3); 


{test} @R 9 TextAttr ‘= SCB: 

{test} write( *<’, Count, ’>’ ); 

{test} TextAttr := SF; 

{test} for i ‘= 1 to Count do write( chr( Beippufferlil ) ); 


BlockWrite( OutFile, Buffer, Count, Result 3; 
until(€ Count <> BufSize ) or ¢€ Result <> CountQigpj ): 
close( OutFile );: 
close( InFile ); 

end; 
readin; 
end. 


Typed File Operations 


The third form of disk file operations involves typed files. For demonstration, the 

TransAct record type introduced in Chapter 9 can be used to create a file of records. 

This will also be the next step in evolving the checkbook program, as Check3.PAS. 
As with other file types, the first step is to declare a file variable: 


var 
BankFile : file of TransAct; 


Of course, the type declaration for TransAct precedes the variable declaration 
but has remained unchanged since Check2.PAS. 

One change from Check2.PAS to Check3.PAS is that the instructions for reading 
a data entry and reporting a data entry have moved from the main body to two 
subprocedures, but this does not affect the processes themselves, only the structural 
organization of the program. 

In addition, after declaring a file variable, two new subprocedures are created: 
first to write a data record to the file, and second, to retrieve a data record. 

However, even though the data file will be repeatedly opened and closed within 
these two subprocedures, the assign statement appears and is executed only once, 
in the main body of the program: 


assign(€ BankFile, FileName ); 
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Once the file variable BankFile has been assigned the desired filename, this 
association remains in effect until either the program terminates or another assign 
statement associates this file handle with a new file specification. Thus, there is no 
need for the assign statement to appear or be executed more than once. 


Writing to a Typed File 


The Save_Record procedure writes the Entry data record to BankFile, beginning by 
reopening the file for each data entry. 

Since the program has no way of knowing if this is a new file or an existing file 
being opened to append new records, Save_Record begins by requesting a reset 
operation: 


{$I-} reset( BankFile ); {$I1+} 
if I0Result <>: 0 
then rewrite( BankFile ) 


Error checking is turned off during the reset operation so that IOResult can be 
explicitly tested to determine success or failure. If [OResult is not zero, i.e. if an error 
message returned, the assumption is that no existing file was found, and therefore, 
a new file should be created by calling rewrite. 

If IOResult does return zero, indicating the file does exist, a different response 
is required: moving the file pointer to the end of the file: 


else seek( BankFile, filesize( BankFile ) ); 


The seek command is called with the file handle, BankFile, and a second 
parameter, filesize( BankFile ), which specifies the size of the file in bytes. In this 
fashion, the seek instruction is told to find the end of the file, which, in effect, 
positions the file pointer to the end of the file. 

The filesize function returns the number of components in the file, not the total 
size of the file. This is a longint value, which will be zero if the file is empty. 

If the file pointer is not positioned to the end of the existing file, the next record 
written to the file is written at the beginning of the file and will overwrite an existing 
entry. In this example, this results in the file never growing beyond one record in 
length. 

There are occasions, however, when overwriting a file record can be desirable, 
or when random rather than sequential access to a file is desirable. Techniques for 
these purposes will be shown presently. 
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For the moment, the file pointer is moved to the end of the file, ready to add a 
new entry using the write command. 


write(€ BankFile, Entry ); 
close( BankFile ); 


After this record is written, the file is closed again, because the next operation 
may not be adding another record. Instead, it might be to reset the file to read 
records from the top, or it could be the end of the program. 

The write command has not previously been shown using a file variable 
parameter, but, as explained earlier for the writeln command, the write command 
is used to output information to a disk file or to devices such as printers, modems 
or other I/O channels. 

However, while the writeln procedure is used for text files, only the write 
procedure is appropriate or valid for typed or untyped files. The reasons for this 
are obvious with a moment's consideration: the writeln procedure adds a CR/LF 
(ODh, OAh) character pair to the output file, which is not an appropriate addition 
to a typed or untyped file. 


Reading From a Typed File 


The second new feature added to the Check3.PAS program is the capacity to read 
records in from the data file, as demonstrated by the List_Entries procedure. 

As with the Save_Record procedure, List_Entries begins by calling reset to 
reopen the data file and position the file pointer to the beginning of the file. 


{$I-} reset( BankFile ); {$I1+} 
if IOResult = O then 
begin 

IOResult is tested here also, but in this instance, only for the purpose of 
determining that the file does exist. If no file exists, List_Entries simply returns, 
doing nothing more. 

Reading an entry froma typed file is just as simple as writing one was. The only 
difference is that nothing is required here to position the file pointer, since reset has 
already placed the file pointer at the beginning of the file. 


read(€ BankFile, Entry ); 
Report_Transaction; 
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Since the Entry record is global in the example, the same Report_Transaction 
procedure that is used when creating a data entry is used now to report the entry 
read from the file. 

Here also the read procedure is shown in a new form, using a file variable to 
specify where information is being read from. This variation was demonstrated 
before with the readln procedure, but for typed or untyped files, the readln 
procedure is not applicable, since it requires a carriage return (ODh) before it 
returns. The read procedure, however, does not require a terminating character, but 
returns after reading exactly the amount of information required by the variable 
data parameter. 

As each data record is read, the file pointer is updated to point one byte past 
the end of the data accessed, that is, at the beginning of the next record. Because of 
this, no seek procedure is needed to access subsequent records. 

For the same reason, the file is not closed after reading each record because this 
would require repositioning the file pointer to find subsequent records after each 
reset. Before leaving the List_Entries procedure, however, the close command is 
called in the usual fashion: 


close( BankFile ); 


Random Access to Typed File Entries 


Typed files often use random access methods to read or rewrite specific entries 
without having to search sequentially through the entire length of a large file. 

The mechanism for locating a specific record within a file is relatively simple: 
call the seek procedure with the offset, within the file, of the first byte of the desired 
record. This positions the file pointer to the first byte of the requested record. For 
example, to find the Nin entry ina file of records, the appropriate instructions would 
be: 


reset( FileVar ); 
seek Evtever, sizeott:.-Filerkec: }) * £ Noe tye 


In this fashion, the file pointer is reset to the beginning of the file and then the 
seek instruction moves the file pointer to the first byte of the Nt entry, making the 
file ready either to retrieve or to overwrite the Nin entry. 

Random access to a record file does presume one bit of information that is not 
automatically available—which record number is desired. Because of this, random 
access is usually employed in either of two circumstances. 
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First, when a file of records is too large to keep all in memory at one time, an 
index to the file can be created by reading through the file and creating an array of 
index records, which contain either the record number or file position plus one or 
more index fields. 

The FilePos function can be used here, before each record is read from the file 
to return the current file pointer position: 


FilePos( FileVar ) 


Once the index is created, individual records can be found, accessed or rewrit- 
ten as required without the delay involved in sequentially searching though the file 
for each specific record. 

Second, an application may need to change one or more records without 
rewriting the entire record file. Precisely this will be demonstrated in a later version 
of the checkbook program. 

This same technique might be used to rearrange a file of records, putting them 
into a specific order by swapping two records at a time. This is actually a slight 
misdescription; what is actually done is to overwrite two records, one at a time, but 
the end result is still exchanging the order of two records. This is not, however, 
recommended, simply because it is both time consuming and usually unnecessary. 


Predefined Streams 


Various compiler languages use different terms—stream, device, channel or file— 
to refer to communication streams, which are used to read from and write to not 
only disk files, but also the keyboard, video, serial and parallel ports, and any other 
I/O devices that may be installed. 

The term stream does not impose the restrictive connotations implied by the 
terms file or device. However, Pascal documentation customarily employs the term 
file or, occasionally, device to denote hardware I/O. 

Whichever term is used, they all refer, from a programmer’s viewpoint, to 
communication channels used to transfer information. 

At the same time, the DOS operating system and Turbo Pascal treat external 
hardware I/O devices such as the keyboard, video display, printer, modem and 
mouse, as file devices, communicating with them through data streams. 

The names for these predefined DOS devices include CON, LPT1, LPT2, LPT3, 
PRN, COM1, COM2, COM3, COM4, AUX and NUL, and can be used exactly as if 
they were conventional filenames. 
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CON refers to the console device, where output is directed to the screen and 
input received from the keyboard. When no file handle is specified, as with the 
write, writeln, read and readIn procedures, input and output are directed by default 
to the CON device. : 

The console is also referenced by the predefined standard files Input and 
Output, which, incidentally, do not require assign, reset, rewrite or close instruc- 
tions. 

LPT1, LPT2 and LPT3 refer to the three parallel port assignments, used, 
customarily, for printer communications. The synonym PRN corresponds to LPT. 

Here is an example of printer output. Be sure that your printer is on before 
executing this example. 


var 
Lats: ext 
begin 
assienG tet, ' PRN); 
rewritet Let: 2: 
uritetnt tet, ‘Sending outout te orinter’ 2); 
etoset Let 2: 
end. 


The unit Printer declares a text file variable titled Lst referring to the LPT1 
device. 

COM1, COM2, COM3 and COM4 define four serial communication ports, 
though most systems have only COM1, or COM1 and COM2 installed. The syn- 
onym AUX refers to COM1. 

NUL is a null device, which simply ignores everything written to it. This is 
useful for testing without the need of creating a specific input or output file. 


Setting the File Mode 


The System unit defines a variable, FileMode, which sets the access code passed to 
DOS when typed or untyped files are opened using the reset procedure. This does 
not affect text files or files opened with rewrite. Table 10-1 lists the valid FileMode 
Settings. 

Modes 0..2 are valid for all versions of DOS, but in DOS version 3.x and later, 
additional modes are defined, principally for network file-sharing operations. For 
further details, see the DOS programmer’s reference manual. 
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Table 10-1: Valid FileMode Settings 
Mode Value Mode Restriction 


0 read only 

1 write only 

2 read/write (default) 
/O Functions 


Turbo Pascal provides a full set of procedures and functions for file (stream) 
input/output operations. Files may be physical disk files or other input/output 
devices, including printers, modems, keyboard and video display. The remainder 
of this chapter is a dictionary listing of Turbo Pascal’s I/O routines. 


Append Procedure TURBO.TPL 


The append procedure reopens an existing text file, and positions the file pointer 
at the end of the file, ready for updating. 


Declaration: Append( var Fil : text ); 


The append procedure is called with an established text file handle which has 
been opened and closed. The file is reopened as write-only, prepared for additional 
entry. 

If the existing text file is terminated by a Ctrl-Z (1Ah) end-of-file marker in the 
last 128 bytes, the current file position is set to overwrite the EOF marker. 

If append is used on a file originally assigned with an empty name, the 
reopened file is directed to the standard output file (standard file handle number 
1). 

With {$I-}, [OResult returns 0 if successful; otherwise returns a non-zero error 
code. 


See also: Assign, Close, Reset, Rewrite 
Example: 
var 
roi ss tents 
begin 
assign( Fil, "TestOut.Txt" J; 
rewritet Fil oO; 
weitetat Fria. First tine of textiicneaet are 
elo@ge¢ -FIL.23 
append( Fil ); 
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wrTeet ne Fits fia. end - this: 1s eppendeéed: text 7; 
eLoset tt 73 
end. 


Assign Procedure TURBO.TPL 


The assign procedure associates an external filename with a file variable. 
Declaration: assign( var Fil; Name: string ); 


Fil is a file variable of any type: text, typed or untyped. Name is a string 
expression in the format [d:\] [path\] name [.ext], where the drive, path and 
extension are optional. If path begins with a backslash, the path specification begins 
in the root directory of the current drive, otherwise the current directory is used. 

Predefined device (stream) names may also be used. (See the section "Pre- 
defined Streams" in this chapter.) 

When name is an empty string (name[0] = 0), filis associated with the standard 
input or output file, permitting use of the redirection feature of the DOS operating 
system. Reset associates fil with the standard input file; rewrite associates fil with 
the standard output file. 

Files must be closed before assign can be used. Do not attempt to use assign on 
any open file. 


See also: Append, Close, Reset, Rewrite 


AssignCrt Procedure CRT 


The AssignCrt procedure associates a text file with the CRT (console). This proce- 
dure is the same as assign except that no file handle is specified. AssignCrt provides 
faster output and input than standard I/O. 


Declaration: AssignCrt( var Fil: text ); 
Example: 
uses Crt; 
var 
Pt - 2 eee 
begin 
Assiontett Fil? 
rewritet. F402} 
writeln( 'Ready?' ); readln; 
writeln(€ ‘Demonstrates normal output to screen ...' ); 
writetine Fit. ee She Feet CUtpUut: te screen: using. *,> 
WERT routines’. 23 
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readln; 
end. 


BlockRead Procedure TURBO.TPL 


The BlockRead procedure reads one or more records into a variable or variable 
array. 


Declaration: BlockRead( var Fil: file; var Buffer; Count: word 
[ ; var Result: word ] ); 


Fil is an untyped file, Buffer, a variable or variable array, Count, a word 
expression and Result, a word variable. 

BlockRead reads Count or fewer records from Fil into Buffer. The optional 
parameter Result returns with the actual number of records transferred. However, 
if Result is not used, an I/O error will occur if fewer than Count records are 
transferred. 

The current file position is advanced by Result records. 

With {$I-}, I[OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 

See the section “Untyped File Operations” for further details and examples. 


See also: BlockWrite 


BlockWrite Procedure TURBO.TPL 


The BlockWrite procedure writes one or more records into a variable or variable 
array. 


Declaration: BlockWrite( var Fil: file; var Buffer; Count: word 
[ ; var Result: word ] ) 


Fil is an untyped file, Buffer, a variable or variable array, Count, a word 
expression and Result, a word variable. 

BlockWrite writes Count or fewer records from Buffer to Fil. The optional 
parameter Result returns the actual number of records transferred. However, if 
Result is not used, an I/O error will occur if fewer than Count records are 
transferred. 

The current file position is advanced by Result records. 

With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 
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See the section “Untyped File Operations” for further details and examples. 
See also: BlockRead 


Close Procedure TURBO.TPL 
The Close procedure closes an open file. 


Declaration: Close( var Fil ); 


Fil is a file variable of any type which was opened with Reset, Rewrite or 
Append. When Close is called, the external file or device is completely updated 
and then closed. The DOS file handle is freed for reuse. 

With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: Append, Assign, Reset, Rewrite 


Eof Function TURBO.TPL 


The EOF function returns a boolean result indicating the end-of-file status of a text, 
typed or untyped file. 


Declaration: Eof( var Fil ): boolean; 
or: Eof( var Fil: text ): boolean; 


If Fil is not specified, the standard file variable Input is assumed. Eof returns 
True if the current file position is beyond the last component of the file or if the file 
is empty; otherwise, False is returned. 


See also: Eoln, SeekEof 


Eoln Function TURBO.TPL 
Eoln returns the end-of-line status of a text file. 


Declaration: Eoln( var Fil: text ): boolean; 


If Fil is not specified, the standard file variable Input is assumed. Eoln returns 
True if the current file position is at an end-of-line marker (ODh or OAh), or if Eof 
(Fil ) is True; otherwise, False is returned. 

On standard input that has not been redirected, Eoln will wait for a carriage 
return from the keyboard, the equivalent of read|n;. 


See also: Eof, SeekEoln 
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FilePos Function TURBO.TPL 


The FilePos function either returns the current file position as the offset in file 
components from the beginning of the file, or returns 0 if the current file position 
is at the beginning of the file. 


Declaration: FilePos( var Fil ): longint; 


With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: FileSize, Seek 


FileSize Function TURBO.TPL 


FileSize returns the number of components of an open file, or zero if the file is empty. 
Declaration: FileSize( var Fil ): longint; 

FileSize cannot be used with a text file or with a closed file. The value returned 
is not the size of the file in bytes, unless, of course, the component size has been set 
to one byte by reset or rewrite. Absolute file size can be calculated as FileSize( Fil ) 
* sizeof( FileRec ). 

With {$I-}, LOResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: FilePos 


Flush Procedure TURBO.TPL 
The Flush procedure flushes the buffer of a text file open for output. 


Declaration: Flush( var Fil: text ); 


With a text file opened for output using rewrite or append, flush empties the 
file buffer, writing the contents to the output file. Flush has no effect on text files 
opened for input. 

With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


lOResult Function TURBO.TPL 


[OResult returns an integer value with the error status of the last [/O operation 
executed. 
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Declaration: [OResult: word; 


To use IOResult, I/O error checking must be turned off by the {$I-} flag before 
the tested I/O operation is executed. If this is not done, internal error checking will 
terminate program execution when an error occurs. 

Also, the {$I+} flag should be used to restore I/O error checking after the 
operation. The call to [OResult clears the internal error flag. Error values and 
corresponding messages are found in Appendix A of the Turbo Pascal Programmer's 
Guide under I/O Errors. 


Read (file) Procedure TURBO.TPL 


The Read procedure reads one or more values or file components into one or more 
variables. 


Declaration: Read( Fil, var V1 [, V2,..., Vn |); 


With text files, each Vn may be a variable of type char, integer, real or string. 
With any other file type, each V must be a variable of the same type as the 
component type of Fil. 

With text files and Vn of type char, read reads one character from the file for 
each variable, assigning one character to each Vn. 

For V of type integer, again with a text file, read expects a sequence of characters 
forming a signed, decimal or hexadecimal value. Leading blanks, tabs or end-of-line 
markers are skipped. Hexadecimal sequences must begin with the $ character as 
the first non-blank character, and the substring read ends with the first blank, tab 
or end-of-line marker following the numeric string, or when the end of the file is 
reached. If the numeric string does not conform to the expected format, an1I/O error 
occurs. The numeric string is converted to a value before assignment to Vn. 

Continuing with text files, for Vn of type real, again, a sequence of characters 
forming a signed real value is expected. Restrictions are the same as for type integer, 
except that hexadecimal expressions are not valid. 

With a string variable, Vn, read reads all characters up to, but not including, the 
next end-of-line marker or until the end of the file is reached. If the resulting string 
is longer than the string variable, the string passed to the variable is truncated. The 
next read will begin with the end-of-line marker that terminated the current string. 

Successive calls to read cannot be used to retrieve a sequence of strings, because 
the current position will not be advanced beyond the first end-of-line marker 
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encountered. Instead, readIn should be used. However, if the next variable read is 
of type char, real or integer, then file [/O continues with the next file line. 

With a non-text file, one file component is read for each variable V with the 
current file position advanced to the next component of Fil. An error occurs if an 
attempt is made to read past the end of the file. 

With {$I-}, LOResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: ReadIn, ReadKey, Write, Writeln 


ReadLn (file) Procedure TURBO.TPL 
ReadIn executes the read procedure, then skips to the next line of text. 
Declaration: ReadLn( var Fil: text; V1 [, V2, ..., Vn ] ); 


ReadIn is an extension of the read procedure for text files only. If readIn is called 
with no variable parameters, the current file position is advanced to the next 
end-of-line marker, if any; otherwise, to the end of the file. If no file parameter is 
supplied, the standard input is assumed. 

With {$I-}, IOResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: Read 


Reset Procedure TURBO.TPL 
Reset opens an existing file. 
Declaration: Reset( var Fil [: file] [; RecSize: word ] ) 


Fil is any type file variable that has been associated with an external file or 
stream using assign. RecSize is an optional expression used only with untyped files. 
Reset opens an existing external file with name assigned to Fil. If the file named 
does not exist, an I/O error occurs. If Fil is already open, it is first closed and then 
re-opened. The current file position is set to the beginning of the file. 

If Fil is a text file, the file is opened as read-only. If Fil is an untyped file, the 
optional RecSize specifies the record size to be used. If RecSize is omitted, a default 
record size of 128 bytes is assumed. 
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With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: Append, Assign, Close, Rewrite, Truncate 


Rewrite Procedure TURBO.TPL 
Rewrite creates and opens a new file or opens and truncates an existing file. 
Declaration: Rewrite( var Fil |: file] |; RecSize: word | ) 


Fil is any type file variable that has been associated with an external file or 
stream using assign. RecSize is an optional expression used only with untyped files. 

Rewrite opens and truncates any existing external file with a name assigned to 
Fil or, if the file named does not exist, creates a new file with a size of 0. If Fil is 
already open, it is first closed and then re-opened. The current file position is set to 
the beginning of the empty file. 

If Fil is a text file, the file is opened as write-only. 

If Fil is an untyped file, the optional RecSize specifies the record size to be used. 
If RecSize is omitted, a default record size of 128 bytes is assumed. 

With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: Append, Assign, Reset, Truncate 


Seek Procedure TURBO.TPL 


Seek moves the current file pointer to a specified offset from the beginning of the 
file. 


Declaration: Seek( Fil; N: longint ) 


Fil is any file type except text, while N is an expression of type longint. The 
current file pointer of Fil is moved to the N ia component of Fil. 

With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: FilePos 


SeekEof Function TURBO.TPL 


SeekEof returns the end-of-file status of a file. 


Chapter 10: Streams, Files, and Device I/O 171 








Declaration: SeekEof( var Fil : text ): boolean; 


SeekEof corresponds to the Eof function, with the difference that SeekEof skips 
all blanks, tabs and end-of-line markers before returning the end-of-file status. It is 
useful when reading numeric values from a text file. 

SeekEof works with text files only. The file must be open. 

With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: Eof, SeekEoln 


SeekEoin Function TURBO.TPL 
SeekEoln returns the end-of-line status of a file. 
Declaration: SeekEoln( var Fil: text ): boolean; 


SeekEoln corresponds to the Eoln function with the difference that SeekEoln 
skips all blanks and tabs before returning the end-of-line status. It is useful when 
reading numeric values from a.text file. 

SeekEoln works with text files only. The file must be open. 

With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: Eoln, SeekEof 


SetTextBuf Procedure TURBO.TPL 
SetTextBuf assigns an I/O buffer to a text file. 
Declaration: SetTextBuf( var Fil: text; var Buffer [; Size: word ] ) 


By default, each text file variable has an internal 128-byte buffer used for read 
and write operations. [/O-intensive applications, such as file copy or text conver- 
sion programs, may benefit from a larger buffer to reduce disk tracking operations 
and file system overhead. 

The SetTextBuf procedure associates a new buffer with the text file Fil. The 
association remains in effect until Fil is next used with the assign command. 

The size parameter is optional, and normally omitted, but may specify a size 
smaller than the size of the buffer. When the size parameter is omitted, the default 
size is assumed to be sizeof( Buffer ). 
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WARNING: SetTextBuf can be called immediately after reset, rewrite or 
append, but should not be applied to an open file after any I/O operations have 
occurred. Once I/O operations have commenced, the change of buffer assignment 
can cause a loss of data. 

Also, Turbo Pascal does not test the validity of the buffer for the entire duration 
of I/O operations. One common error is for a buffer to be declared as a variable 
within a subroutine and then file I/O executed outside the valid scope of the buffer. 
Example: 
const 

FileName = 
var 
Putt text? 
Ch 3: Cher? 
Buffer ©: arrayl1..51201 of chars © SK butter } 
begin 
assign( Fil, FileName ); 
SetTextButt Fil, Butter -7; 
reset Fil 2; 
while not eof(€ Fil ) do 
begin 
PrenaGic Pit, Ch 2 
wrptcet: Ch >> 
end; 
clesetcRrtTt 3; 
end. 


Truncate Procedure TURBO.TPL 
The Truncate procedure truncates the open file at the current file pointer position. 


Declaration: Truncate( Fil ); 


Fil is any type of file variable. All file components beyond the current file 
position are deleted, and the current file position becomes the end of the file. 

With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: Reset, Rewrite, Seek 


Write (file) Procedure TURBO.TPL 


The write procedure writes one or more variables to an output file. 
Declaration: Write( | var Fil; ] V1 [, V2,..., Vn ] ); 
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If Filis a text file, the write procedure writes a formatted string to the file using 
the same formatting options as discussed in Chapter 7. 

If Fil is a typed file, each variable V is written to a filecomponent and the current 
file position advanced to the next component. When the current file position has 
reached the end of the file, the file is expanded. The formatting options shown for 
text files do not apply. 

With {$I-}, [OResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


WriteLn (file) Procedure §TURBO.TPL 


The writeln procedure executes the write procedure before appending an end-of- 
line marker (a CR/LF character pair) to the output. 


Declaration: Writeln([ var Fil; ] V1 [, V2, ..., Vn ] ); 


The writeln procedure applies only to files of type text. If writeln(Fil) is called 
with no further parameters, an end-of-file marker is written to the file. 

With {$I-}, lLOResult returns 0 if successful; otherwise, returns a non-zero error 
code. 


See also: Write 


Summary 


In this chapter you have looked at file operations in Turbo Pascal and seen 
demonstrations of the three basic file types: text, typed and untyped. The chapter 
has expanded the definition of the term file beyond a disk file to include any 
input/output channel, which may also be a device such as the CRT, keyboard, or 
parallel or serial ports, which have predefined filenames or handles. 

This chapter also expanded the checkbook program introduced in Chapter 9 to 
include writing a file of records and reading the records back for display. This 
program will be further expanded in subsequent chapters. 

Following are the complete program listings for the demo programs illustrating 
the file operations discussed in this chapter: 
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{ } 
{ ReadText.PAS } 
{ demonstrates opening and } 
{ reading, writing and } 
{: elosing text Fites } 
{ } 


uses Crt; 


const 
FileName = 'READTEXT.PAS'; 
FileName2 = 'READTEXT.OUT'; 
var 


TextFite, OutText :. text; 
TextLine : string; 


begin 
assign( TextFile, FileName ); 
{$I-} reset( TextFile ); {($I1+} 
if I0Result <> O then 
begin 
uritetint. ‘The file’, Fiteneme, ': can not be found!" >; 
Sound¢ 220 7): detbay¢ 100203 
Sound( 440 ); delay( 100 ); 
NoSound; 
end else 
begin 
assign( OutText, FileName2d ); 
rewrite( OutText ); 
while not EOFC TextFile ) do 
begin 
readln( TextFile, TextLine ); 
writeln( TextLine ); 
writeln( OutText, TextLine ); 
end; 
close(€ OutText ); 
close( TextFile ); 
end; 
readln; 
end. 
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ee eee ee ee 
{ CpyBlock.PAS } 
{ demonstrates the BlockRead_ } 
{ and BlockWrite procedures } 
(sS2SS2SS2Seeeeeeee2eeeeeee====} 


uses. Crt, 


const 
InFileName 
OutFileName 


'CPYBLOCK.PAS'; 
'CPYBLOCK.NEW'; 


var 
1 © integer: 
infitte, Gotrhkite +s Ft1Le-? 
BufSize, Count, Result : word; 
Butter : arraytt,..1281] of: Bytes 


begin 

BufSize := sizeof( Buffer ); 

assign( InFile, InFileName ); 

{$I-} reset( Infile, 1 )3; {$I+} 

if I10Result <> O then 

begin 
writeln( 'The file ', InFileName, 

. ‘ean not Be Tound?* 3: 

Sound(€ 220 ); delay( 100 ); 
Sound(€ 440 ); delay( 100 ); 
NoSound; 

end else 

begin 
assign(€ OutFile, OutFileName ); 
{$I-} rewrite( OutFile, 1 ); {$I+} 
repeat 

BlockRead( Inf ite, Buffer, BufSize, Count +? 


{test} TextAttr := $0OC; 

{test} weiteat *<*, Count, *s* J; 

{test} TextAttr := $OF; 

{test} for 7 $= 1 to Count do write: ehtt: Bufferlid ) 


BlockWrite(€ OutFile, Buffer, Count, Result ); 
until( Count <> BufSize ) or CC" Reaguie: <2 Count: ): 
close( OutFile ); 
close( InFile ); 

end; 
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readln; 
end. 
{seeseseesessessszessesses=sz} 
{ Check3.PAS } 
{ saving @ tilecot records. > 
{(sasessestseesessessssssz====} 
uses Crt; 
const 
FileName = 'BANK.ACT'; 
type 
Transaction = ( Nulli1, Debit, Credit, Other ); 


Special = (€ Null2d, Overdraft, 


DateRec = record 


{ so. same as. Checkd.PAS 


TransAct = record 


{ 2) game as Checkdéd. PAS 


var 
Entrx sc Pransact; 


BankFitle  : Tile of TransAct; 


Quit : boolean; 


procedure Beep; 
Cos oe es. Cheend:. 


function ReadData( 
fos eee a8 Ch ecke:. 


function ReadwWord( ; 
{ vy eeme- ee" Checkd. 


procedure ReadDate( 
Cue eee ae Checke, 


procedure ReadReal ¢ 
{ ... same as Checked. 


function SelectAction 
€ -. ec eemeies: Checkd. 


function SelectOther : Special; 


{ 636 See ae Chet Ke. 


PAS 


PAS 


PAS 


PAS 


PAS 


Transaction; 


PAS 


PAS 


Service, Interest, 


} 


} 


} 


} 


} 


Adjust ); 
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procedure Read_Transaction; 
begin 
with Entry do 
begin 
Cleared := False; 
ReadDate( 2, 3, TransDate ); 
Action := SelectAction; 
ReadReal( 2, 4, ‘Amount', Amount ); 
case Action of 
Debit : begin 
CkNum := ReadWord( 20, 3, 'CheckNum', 
CkNum, 5 ); 
PaidTo:. t= Reeaddatat 20,;:4,-'Paid to', 
Sizeorte -FatdTo >) ds 
end; 
Ered tt: © 2 
Other : Itemtype := SelectOther; 
end; {case} 
Comment := ReadData(C 2, 5, 'Comment', 
sizeof( Comment ) ); 
end: < with 2 
writeln; 
end; 


procedure Report_Transaction; 
begin 
writeln; 
with Entry do 
begin 
case Action of 
Debit : write( 'Check Number: ', CkNum ); 


Credit : write( 'Deposit: ee 
Other : case Itemtype of 
Adjust : write(€ ‘Adjustment ' ); 
Interest : write(€ ‘Interest earned ' ); 
Overdraft : write(€ ‘Overdraft ' ); 
service : writet.."Service charges ' )? 


end; {case} 

end; {case} 
with TransDate do 

wert teLyt =* Dates) Meneses» bey, -"'/', Yer 2: 
write * Amount: S$", “Amount :S:2.27: 
if Action = Debit then writeln(¢ ' Paid to: ', PaidTo ) 

else writeln; 

writeln( ‘Comments <'s*:Comment.2- 
writeln; 
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end; { with } 
end; 


procedure Save_Record; 


var 
Choos -efary 
begin 
repeat 
Beep; 
writet ? Save this entry? 6ctne: 8272 
Ch := upcase( ReadKey ); 
onee Ce Ee ao LY eer UCR esas 
FO CH eel yy. 2 hes 
begin 
wrs Cetin’: Saving -enthy. .ew 33 
Beep; 
{$I-} reset( BankFile ); {$I1+} 
if 10Result <> O 
then rewrite( BankFile ) 
else seek( BankFile, filesize( BankFile ) ); 
write BankFite, Entry 23 
close( BankFile ); 
Beep; 
end; 
writeln; 
end; 


procedure Record_Entry; 

begin 
Read _ Transaction; 
Report_Transaction; 
Save_Record; 
writeln; 

end; 


procedure List_Entries; 
var 
Done : boolean; 
begin 
Done := False; 
{$I-} reset( BankFile ); {$1+} 
if I10Result = O then 
begin 
repeat. 
réad( BankFile, Entry; 
Report_Transaction; 
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1f not EOFC BankFile ) then 
begin 
write€ "Select <Q>uit or any key '! 
"TOF HOxt record * d-: 


Done := upcase( ReadKey ) = 'Q!; 
writeln; 


end else Done := True; 


7 


begin | 
write "hit any key to continue *); 
readln; 
Done := True; 

end; 


until Done; 

close( BankFile ); 
end; 
end; 


begin 
clrecrs 
assign(€ BankFile, FileName ); 
Quit := False; 
repeat 
Eliracer: 
write(€ "Select <R>ecord transaction, ' 
(<L>3st records -or <Qeuit * )- 
case upcase( ReadKey ) of 
"R*:. Recorad_Entry; 
"bt. 2 ASE ERS i4es 
"a": Quit 2] True’ 
end; {case} 
writeln; 
uUNnETEL Gattz 
end. 


t 
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Chapter 11 


Disk File Operations 


Chapter 10 introduced processes for reading and writing disk files. Creating and 
accessing files, however, are only part of the disk operations you will need. Turbo 
Pascal offers a full range of disk information and maintenance routines including: 
procedures that parallel such familiar MS-DOS operations as MkDir and ChDir, 
procedures for deleting or renaming existing files, and procedures for locating files, 
reading directory and file lists, and reading or setting file access flags and file 
date/time stamps. Turbo Pascal also provides methods for both assembling and 
disassembling fully qualified path/filenames. 

Before we begin to examine Turbo Pascal’s disk operations, you should note 
that while some of these routines reside in the standard library, TURBO.TPL, most 
are supported by library functions in the DOS unit. Before you can access the DOS 
unit procedures, you must specify the DOS unit in a uses statement, thus: 


uses Crt, b6¢ 


Getting Disk Information 


Two primary questions can be asked about a floppy or hard disk: first, how much 
free space exists on the media, and, second, what is the total capacity of the media? 
The DiskFree and DiskSize functions, both located in the DOS unit, provide this 
information. 
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DiskFree Function DOS 


The DiskFree function is called and returns a longint value reporting the number 
of bytes of free space on the specified drive. 


Declaration: DiskFree( Drive: byte ): longint 


The calling parameter, Drive, uses a value of 0 to indicate the default (active) 
drive, 1 for drive A:, 2 for B:, and so on. DiskFree returns the error code —1 if an 
invalid drive number is requested. 


See also: DiskSize 
Example: 
uses Dos; 
var 
Free : lLongint; 
begin 
Free := DiskFree( O ); 
writeln( 'Space available on the active (default) ', 
drive 16°); Fre@ee;: "Bytes or: *; 
Pree dtv: 10246) = hoppy tes: *: 7} 
end. 


DiskSize Function DOS 
The DiskSize function returns the total byte capacity of the specified disk drive. 
Declaration: DiskSize( Drive: byte ): longint 


The calling parameter, Drive, uses a value of 0 to indicate the default (active) 
drive, 1 for drive A:, 2 for B:, and so on. DiskSize returns the error code —1 if an 
invalid drive number is requested. 


See also: DiskFree 

Example: 

uses Dos; 

const 
Kilo = 1024; 

var 
Size: lLongint; 

begin 
Size. 2=:-DiskSizet 0.3; 
wrvteC * Phe disk ee." 33 
S426 ..33 Size div Ki Loe: { change to kilobytes } 
ft: Stze > 1500 then 
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wraitetin( "hard disk with “|, Size div Ki be, 
. Megabyte capactty (', Size, * Kbytes).! ) 
else if Size > 1300 then 
writeln(€ '1.4 Megabyte (', Size, 
“ Kbytes, 3.5 floppy disk.* 2 
else if Size > 800 then 
writeln(€ '1.2 Megabyte (', Size, 
"-KSvytea) 5.259 floppy diaekiina 
else if Size > 400 then 
writetne ‘F200. Kovte-.0:* Size, 
" KO¥tes? 3.5 Tloppy disk." 3 
else 
writetn(t "360 Kbyte. ¢'.,.-Size, 
' Kb¥tes? S242 Fionpay disk." d; 
readln; 
end. 


Both floppy and hard disks are normally referred to as having x kilobytes or x 
megabytes, depending on their capacity, but references such as 360K, 720K, 1.2Meg 
or 1.4Meg are approximations, not accurate descriptions of actual capacity, espe- 
cially for floppy disks. 

When a floppy or hard disk is queried for its capacity, the disk reports its own 
format as w number of bytes per sector, x number of sectors per cluster (usually 1) 
and y number of sectors. MS-DOS also reports z number of clusters, which may or 
may not match with the sectors reported by the disk format information. This is the 
information used to calculate the disk capacity both for floppy disks and for hard 
disks, as reported by the DiskSize function. 

The actual number of bytes (or kilobytes) of disk capacity generally does not 
fall into neat compartments matching our familiar labels, which is one reason that 
a complex if..then..else statement was used in the preceding example instead of a 
simpler case..of statement. 

Table 11-1 shows a comparison between the nominal and actual disk capacities 
for four floppy disks and one hard disk partition. 


Table 11-1: Comparing Nominal and Actual Disk Capacities 
Nominal Disk Size — Actual Capacity 


360K (5.25 inch) 354K 
1.2Meg (5.25 inch) —1,185K (1.157 Meg) 
720K (3.5 inch) 713K 


1.4Meg (3.5 inch ) 1,423K (1.389 Meg) 
40Meg (harddrive)  40,894K (39.935 Meg) 
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Disk Directory Operations 


MS-DOS provides several routines to create or manipulate disk directories and 
subdirectories. Most of these are paralleled by Turbo Pascal procedures with the 
same names and functions, such as ChDir, MkDir and RmDir. All of these are 
included in the standard library, not in the Dos unit. 

Note, that although the MS-DOS synonyms CD for ChDir, MD for MkDir and 
RD for RmDir are not supported by Turbo Pascal, the sample program DirTest.PAS, 
located at the end of this chapter, explicitly creates these synonyms for you. 

The path specifications for all Turbo Pascal directory functions follow the same 
format as MS-DOS path specifications, just as the functions themselves behave in 
the same fashion as their MS-DOS counterparts. 


ChDir Procedure TURBO.TPL 


The ChDir procedure parallels the MS-DOS command ChDir to change the current 
directory and/or drive. 


Declaration: ChDir( DirPath: string ); 


DirPath is a string expression following the standard MS-DOS path specifica- 
tion format. The current (default) path is changed to the path specified. If a drive 
letter is included in the specification, the active (default) drive is changed also. If 
DirPath consists only of a drive specification, the drive is changed, and the last 
active directory on the new drive becomes the active directory. 

You can use the FExpand and FSplit routines to create DirPath string specifica- 
tions for use with ChDir. You can also call ChDir with the relative path instructions 
‘\’ for the root directory or ’..’ for the parent directory instead of a qualified path 
specification. 

With {$I-}, [OResult returns 0 if successful; otherwise a non-zero error code is 
returned. 


See also: GetDir, MkDir, RmDir, FExpand, FSplit 
Example: See DirTest.PAS at the end of this chapter. 
MkDir Procedure TURBO.TPL 

The MkDir procedure creates a new subdirectory. 


Declaration: MkDir( DirPath: string ); 
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DirPath is the string expression MkDir uses to create a new subdirectory. 
DirPath follows the standard MS-DOS path specification format. 

Two restrictions apply: First, the last item in the path specification cannot 
correspond to an existing filename. Second, only one level of subdirectory can be 
created at a time (i.e., two new lévels of subdirectory cannot be created in a single 
step as ’\new1 \new2’). 

You can use the FExpand and FSplit routines to create DirPath string specifica- 
tions for use with MkDir. 

With {$I-}, IOResult returns 0 if successful; otherwise, a non-zero error code is 
returned. 


See also: GetDir, ChDir, RmDir, FExpand, FSplit 
Example: See DirTest.PAS at the end of this chapter. 


RmDir Procedure TURBO.TPL 
The RmDir procedure erases an empty subdirectory. 
Declaration: RmDir( DirPath: string ); 


DirPath is a string specifying the directory path to be removed. It follows the 
same format as the MkDir or ChDir procedures, except that relative path specifica- 
tions cannot be used; only fully qualified path specifications. You can use the 
FExpand and FSplit routines to create DirPath string specifications for use with 
RmDir. 

The specified subdirectory must be empty (i.e., cannot be contain any files or 
further subdirectories) and cannot be the current, active directory. 

With {$I-}, LOResult returns 0 if successful; otherwise, a non-zero error code is 
returned. 


See also: GetDir, MkDir, ChDir, FExpand, FSplit 
Example: See DirTest.PAS at the end of this chapter. 


In addition to the ChDir, MkDir and RmDir procedures paralleling MS-DOS 
commands, Turbo Pascal provides one other directory procedure, which MS-DOS 
doesn’t normally need: a procedure to ask what the current directory is shown below. 
GetDir Procedure TURBO.TPL 


The GetDir procedure returns the current (active) directory on the specified drive. 
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Declaration: GetDir( Drive: byte; var Path: string ); 


GetDir is called with two parameters: a drive specification and a string variable 
that returns with the fully qualified drive/path specification for the requested 
drive. The Drive parameter follows the same format as the DiskFree and DiskSize 
routines, with 0 indicating the default (active) drive, 1 indicating A:, 2 for B:, and 
so on. 

If the specified drive is invalid or not available, no error is reported, but Path 
is returned as the root of the specified drive. For example, if drive B: is called 
without a disk in the drive, GetDir returns Path as ‘B:\’. 

You can use the FSplit routine to ‘decompose’ the Path string specification 
returned by GetDir. 


Example: See DirTest.PAS at the end of this chapter. 


Disk File Operations 


In addition to paralleling the MS-DOS directory operations, Turbo Pascal also 
provides procedures that emulate the MS-DOS Rename and Erase (Del) commands 
and are called in essentially the same fashion. Again, these are included in the 
standard library, not in the Dos unit. 


Rename Procedure TURBO.TPL 
Rename renames an existing external file. 
Declaration: Rename( var Fil; NewName: string ); 


Fil is a file variable of any type, which has been associated with the desired 
target file using the Assign command. NewName is a string expression providing 
a valid MS-DOS filename. The external disk file, Fil, is renamed on disk, and all 
future operations will use the new filename, NewName. 

Rename must not be used on an open file. 

With {$I-}, [OResult returns 0 if successful; otherwise, a non-zero error code is 
returned. 


See also: Erase 


Chapter 11: Disk File Operations 187 


Erase Procedure TURBO.TPL 


The Erase procedure erases an external file. 
Declaration: Erase( var Fil ); 


Fil is a file variable of any type, which has been associated with the desired 
target file using the Assign command. The external disk file, Fil, is erased from the 
disk. | 

Erase must not be used on an open file. 

With {$I-}, IOResult returns 0 if successful; otherwise, a non-zero error code is 
returned. 


See also: Rename 


Locating Files 


Just as MS-DOS provides the PATH specification for subdirectories to be searched, 
Turbo Pascal provides a similar feature allowing a list of directories to be searched 
for a specified file. 


FSearch Function DOS 


The FSearch function searches for a specified file in a list of directories. 
Declaration: FSearch( Target: string; DirList: string): PathStr; 


The Target string specifies the file to search for, while DirList provides a list of 
drive/path specifications to be searched. The drives/directories listed in DirList 
follow the same format as the MS-DOS PATH command, with each directory path 
separated by a semicolon. The file search always begins with the current directory 
of the active drive before searching the directories specified in DirList. 

If Target is found, FSearch returns a drive/path/file specification using the 
drive/path string extracted from DirList. The FExpand function will expand the 
returned filename into a fully qualified filename. 


Example: 

uses Dos; 

var 
Where : PathStr; 

begin 
Where := FSearch( ‘TURBO. EXE';, GetEnvc. .* e478 *..3. 2): 
writeln( Where ); 
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if Where Vea en 
writeln(€ 'Not found' ) else 
writeln( ‘Found as ', FExpand( Where ) ); 
readln; 
end. 


In this example, the GetEnv function returns the MS-DOS PATH directory 
string. 


Qualified Path/Filenames 


Drive, path and file specifications require a specific format and syntax to create a 
fully qualified filename—i.e., a completely specified drive, path, filename and 
extension. 

Turbo Pascal provides two operations, FExpand and FSplit, to assist in assem- 
bling and disassembling fully qualified filenames. Also, in the DOS unit, four string 
data types are defined as: 


type 
PathStr = stringl79]; 
DieStr.-S strineté67i; 
NameStr = stringl81]; 
ExtStr- se stringlald; 


FExpand Function Dos 
FExpand expands a filename into a fully qualified filename. 
Declaration: FExpand( Path: PathStr ): PathStr; 


FExpand accepts a partial or qualified filename in Path, together with relative 
path specifications and/or embedded ’..’ directory references. The returned PathStr 
is converted to uppercase and includes the drive letter, a complete path from the 
root directory and the filename and extension. 


See also: FSplit, FindFirst, FindNext 
Example: See Search.PAS and Read_Dir.PAS at the end of this chapter. 
FSplit Procedure DOS 


The FSplit procedure splits a filename into three components: directory string, 
filename and file extension. 
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Declaration: FSplit( Path: PathStr; var Dir: DirStr; 
var Name: NameStr; var Ext: ExtStr ); 


FSplit is called with a full or partial drive/path/filename string (PathStr) and 
returns three separate strings. Dir returns the drive specification, if any, and the 
directory path with any leading or trailing backslash characters. Name contains the 
eight-character filename. Ext contains the file extension, if any, with a preceding 
period. 

Any of these components may be returned empty if Path does not contain that 
component. 

Unlike FExpand, FSplit does not add or remove any characters when splitting 
PathStr into components. The only components reported are those present in the 
calling parameter string. 


See also: FExpand, FindFirst, FindNext 
Example: See Read_Dir.PAS at the end of this chapter. 


Creating a Directory List 


Disk directories and file entries are written in a record format that is most conve- 
niently accessed using Turbo Pascal’s FindFirst and FindNext procedures. Direct 
access to file directories is also possible through interrupt functions, but these 
provide no additional information or access, while the Turbo Pascal routines do 
provide a great deal of convenience. 

The FindFirst procedure is used to initiate a directory search. If an initial file 
entry is found, the FindNext procedure is used to continue the directory search. 

The FindFirst and FindNext procedures are demonstrated in the Read_Dir.PAS 
program at the end of this chapter. 


FindFirst Procedure DOS 


FindFirst searches the specified directory (or current directory if no path is speci- 
fied) for the first entry matching the specified filename and attribute flags. 


Declaration: FindFirst( Path: string; Attr: word; 
var FileRec: SearchRec ); 


When accessing a directory list, the FindFirst procedure initiates the directory 
search by specifying a directory mask and file attributes. The directory mask may 
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include an optional drive/directory path but must include a file specification, 
which may be constructed using the MS-DOS wildcards “’ and ‘?’. 

The file attribute specification Attr is a bit-mask, which can either be a word 
value or can be created by combining one or more of the file attribute constants 
declared in the DOS unit, for example: 


const { value bit maps. } 
ReadOnly = $01; AS, © Ris Mi © RO Le i Soca ae A 
Hidden = $02; w Same © ial © ier fie  Leaeepaes © Ws # Gey EAs 2 Be 
SysFile = $04; C30 1G ae 
VolumeID = $08; MEO abs * aes YE © Dae Ha 2 Tee tT 
Directory = $10; hae * free 3 taoan # as 5 We © ae ee 
Archive = $20; OS ap 
AnyFile = $3F; Ce Bee s US Mtety Haells Wae 


AnyFile combines all of the attribute flags, but you can create other combina- 
tions as desired. For example, to search only for hidden files that have not been 
backed up (i.e., still have the Archive bit set), you could call the Attr parameter as: 
Hidden + Archive. 

Or, to exclude hidden files and volume id but report everything else, you might 
specify: AnyFile - ( Hidden + VolumelD ). 

The result of the initial file search is returned in the variable search record 
parameter, FileRec. 

The SearchRec data record is declared in the DOS unit as: 


type 

SearchRec = record 
PICs array Tevet Se OF Sy¥te> 
At thE .s byte? 
PAMS's Leongint : 
Site. -vongint; 
Name : stringl121]; 

end; 


The structure of SearchRec is established by MS-DOS interrupt requirements. 

The Fill array returned is a record structure specified by MS-DOS. It contains a 
copy of the information used to locate the first file entry, and will be used by 
FindNext to locate additional files. The Fill array contains the drive number in byte 
one, the file specification mask in bytes 2..12, and the attribute byte in byte 13. Bytes 
14..15 contain the record number of the last match, in the form Isb,msb. Bytes 16..17 
are the record size field. Bytes 18..21 appear to be unused at the present time, but 
may be implemented in future releases of MS-DOS. 
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Find First itself has no error reporting provisions. Therefore, to determine if the 
initial search fails to find a matching entry, you must test DosError for a non-zero 
error report. Possible error codes reported by DosError are: 3 Directory not found, 
or 18 No more files. 


See also: FExpand, FSplit, FindNext 
Example: See Read_Dir.PAS at the end of this chapter. 


FindNext Procedure Dos 


After Find First initiates a file directory search, FindNext is called to return the next 
file entry that matches the name and attributes originally specified for the search. 


Declaration: FindNext( var FileRec: SearchRec ); 


FileRec must be the same record structure initially passed to FindFirst, since 
the Fill field was returned containing the drive, file specification and attribute 
masks for further searches, as well as record and size information for the location 
of the last match found. DosError will report error code 18, No more files when no 
further files are found matching the original file specification. 


See also: FindFirst, FSplit, FExpand 
Example: See Read_Dir.PAS at the end of this chapter. 


Manipulating File Attributes 


Changing file information is accomplished in the same fashion as creating and 
reading files: by using the Assign procedure to associate a file handle (file variable) 
with the filename and then calling the SetFTime or SetFAttr procedure. 

Of course, if date/time and attribute information are going to be set for 
established files, you also need a means of reading the existing information without 
having to go through a directory search. The GetFTime and GetFAttr procedures 
provide this capacity. 

In no case can these procedures be used with open files; any errors will be 
reported by DosError. Possible error codes are included in the description of each 
procedure, below. 


GetFAttr Procedure Dos 
The GetFAttr procedure returns the attributes of a file. 
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Declaration: GetFAttr( var Fil; var Attr: word ); 


Fil is a file variable of any type, which has been assigned but is not open. The 
returned attribute byte can be examined by anding Attr with the file attribute masks 
defined as constants in the DOS unit (see FindFirst). 

Possible error codes reported by DosError are: 3 Invalid path or 5 File access 
denied. 


See also: SetFAttr, GetFTime, SetFTime 
Example: See FileAttr.PAS at the end of this chapter. 


SetFAttr Procedure DOS 
The SetFAttr procedure sets the attribute flags for a file. 
Declaration: SetFAttr( var Fil; Attr: word ); 


Fil is a file variable of any type, which has been assigned but is not open. The 
Attr flag byte may be any byte value or may be created using the file attribute masks 
defined as constants in the DOS unit (see FindFirst). 

Error protection is provided by MS-DOS such that SetFAttr cannot be used to 
assign a Directory or VolumelD flag to a file or to assign Readonly, System or 
Archive flags to directories. The Hidden attribute, however, can be assigned to a 
directory. 

Attempts to assign invalid flags result in an error returned by DosError with 
possible error codes reported as: 3 Invalid path or 5 File access denied. 


See also: GetFAttr, GetFTime, SetFTime 
Example: See FileAttr.PAS at the end of this chapter. 


GetFTime Procedure DOS 


The GetFTime procedure returns the date/time stamp indicating when a file was 
last written. 


Declaration: GetFTime( var Fil; var Time: longint ); 


Fil is a file variable of any type, which has been associated with the desired file 
name using the Assign procedure. The file may be open or closed. The date/time 
stamp returned in Time is a packed longint value, which can be unpacked by 
UnpackTime. 

One possible error code may be reported by DosError as: 6 Invalid file handle. 
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See also: UnpackTime, SetFTime 

Example: See DateFile.PAS at the end of this chapter. 

SetFTime Procedure DOS 

The SetFTime procedure sets the date and time a file was last written. 
Declaration: SetFDate( var Fil; Time: longint ); 


Fil is a file variable of any type, which has been associated with the desired file 
name using the Assign procedure. The date/time stamp passed as Time is a packed 
longint value, which can be created by calling PackTime. 

One possible error code may be reported by DosError as: 6 Invalid file handle. 


See also: GetFTime, PackTime 
Example: See DateFile.PAS at the end of this chapter. 
Note: Close( Fil ) also sets the date/time stamp for the file. 


PackTime Procedure DOS 


The PackTime procedure converts a DateTime record into a 4-byte packed longint 
value. 


Declaration: PackTime( var DT: DateTime; var Time: longint ); 


DateTime is a record structure defined in the DOS unit as: 


type 
DateTime = record 
Year, Month, Day, Hour, Min, Sec + werd: 
end; 


No range checking is applied to the fields in the DateTime record. 
See also: GetFTime, GetTime, SetFTime, SetTime, UnpackTime 
Example: See DateFile.PAS at the end of this chapter. 

UnpackTime Procedure DOS 


The UnpackTime procedure converts a longint packed date/time value into an 
unpacked DateTime record. 


Declaration: UnpackTime( Time: longint; var DT: DateTime ); 
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DateTime is a record structure declared in the DOS unit (see PackTime). No 
range checking is applied to the fields in the DateTime record. 

UnpackTime is used to unpack date/time stamps returned by GetFTime, 
FindFirst or FindNext. 


See also: GetFTime, GetTime, SetFTime, SetTime, PackTime 
Example: See DateFile.PAS at the end of this chapter. 


Verifying File Write Operations 


MS-DOS provides a verify option for file write operations. When the verify option 
is enabled, all write operations are subsequently read back and compared for 
accuracy. Using verification slows disk operations slightly, but ensures that infor- 
mation is not lost due to bad sectors. 

Turbo Pascal provides two procedures for querying and setting the MS-DOS 
verify status. | : 


GetVerify Procedure DOS 
GetVerify returns the state of the MS-DOS verify flag. 
Declaration: GetVerify( var Verify: boolean ); 


When the verify flag is False, disk write operations are not verified. When True, 
all disk write operations are verified for accuracy. 


See also: SetVerify 


SetVerify Procedure DOS 
SetVerify sets the MS-DOS verify flag. 


Declaration: SetVerify( Verify: boolean ); 
See also: GetVerify 


Summary 


Disk operations cover a lot of ground and this chapter has included everything 
from checking the disk for available space, to changing directories, to reading file 
directory lists, as well as reading and modifying disk file attributes and date/time 
stamps. The several demo programs listed below illustrate these topics. 
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Later, many of the elements featured in this chapter are presented in a new 
combination as a utility for file operations. But first, we have several other topics 
to cover. Chapter 12 introduces screen presentations, because how you display 
information can be almost as important as the information itself. 


{Ses SSSS S225 S55 S48 825 S55 e252 522a2 }) 
{ DateFile.PAS } 
{ demonstrates accessing } 
{ file date/time information } 
{sseseeeecessteeesesesssesseeszsese==} 


uses Crt, dos; 


var 
Pak = FikeZ 
TimeStamp : lLongint; 
FileTime : DateTime; 
TMonth, TDay, TYear, WeekDay, 
THowr, thins FSee; secluo.-2. word; 


procedure ReportError; 
begin 
wrttet “Doe Errore. * 33 
case DosError of 
3S: writetn( ‘invalid peth' 2; 
5: writeln( 'file access denied' ); 
6: writeln( ‘invalid file handle’ ); 
end; {case} 
end; 


function Pad¢t Value: word 2): string; 


var 
TempStr: stringl21J; 
begin 
str( Value, TempStr ); 
1f. TempStrEiy = * * then Tempstrlid <= *aQ*, 
Pad := TempStr; 
end; 
begin 
cirser; 


writetnt ParamStrtt) dd: { accepts command Line parameters } 
assigqnt Fil, Paranstrti42): 2: { see ParamStr in Chapter 13 } 
GetFTime( Fil, TimeStamp ); 
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if DosError <> 0 then ReportError else 
begin 


writeln(€ FExpand( ParamStr(1) ), 
* time stamp 18 °)> TimesStamo 2; 
UnpackTime( TimeStamp, FileTime ); 
with FileTime do 
writeln(€ "File date/time stamp =':26, 
"Pate: SS. Bonthy il se aK, os"): Peat year=1900):, 
PT mes $Oo BOE Ue Pag Ntinr,: es, PadtsSec) ) 3 
GetDate( TYear, TMonth, TDay, WeekDay ); 
GetTime(€ THour, TMin, Tsec, Secred:) > 
writeln(€ ‘Current date/time =':26, 
reetes 26, Teer, s") 1oeve Fe") PeecTyYear=-1900), 
raueet "$6. Teeers tel Page rein, "2.5, Peat tsec) 33 
wrvte(: ‘Update :fite etenp? «v7 ee. 2: 
if upcase(€ readkey ) = 'Y' then 
begin 
with FileTime do 
begin 
Month 
Hour 
end; 
PackTime€ FileTime, TimeStamp ); 
SetFTime€ Fil, TimeStamp ); 
if DosError <> 0 then ReportError else 
writeln( ‘File date/time stamp updated ...' ); 
readln; 


TDay; Year := TYear; 
Bik he Wg 1 Sec a Tee 2 


TMonth; Day 
THour; Min 


end; 
end; 
end. 


(ssesseseseeeesseeszsee====}) 
{ DirTest.PAS } 
{ demonstrates directory } 
{ procedures and functions } 
(Sessesstesseesesasteeeese====}) 


uses Crt, Bos; 


var 


DifPatn- 2 string: 


function RDC PathStr: string ): boolean; 


var 


Result: boolean; 
begin 
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{$I-} Rmdir€ PathStr d: {$14} 
Result := I0Result = O; 
if Result then writeln( PathStr, ' has been removed' ) 
else writeln(€ ‘Could not remove ', PathStr ); 
RD := Result; 
end; 


procedure MDC PathStre string ); 
begin 
{$I-} MkDir( PathStr ); {$I+} 
if I10Result <> QO 
then writeln(€ ‘Could not create ', PathStr ) 
else writeln( PathStr, ' now exists' ); 
end; 


procedure CDC PathStr: string >>; 
begin 
{$T-} ChDir¢ PathStr 3; {$I+} 
if I0Result <> O 
then writeln(€ ‘Could not change to ', 
FExpand( PathStr ) ) 
else writeln(€ ‘Current directory is ', 
FEXDanat “Paenétr-) I; 
end; 


begin 
Cirsers 
GetDirt GO, DirPath 2): 
writeln( "The current directory is ', DirPath 3); 
DirPath := DirPath + "\TESTING': 
MOC DirPath 23 
COX DirPath 2 
if not ROC BirPathn >» Then 
begin 
CE. wa 22 
if RDC DirPath ) then; 
end; 
GetDir( O, DirPath ); 
writetnt "The eurrent directory: i¢6 *, 2eotrreth.)? 
readln; 
end. 


can't delete same directory } 
VOu're Currently in «.. 80 2 
go to root of this dir and } 
now delete this directory } 


a Aa Ae 
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{sseseeeesezseseseesessessseezs} 
{ FileAttr.PAS } 
{ demonstrates accessing } 
{ file attribute information } 
{ees essestesseeesseecsssseses=seea } 


uses Crt, Dos; 


const 
Attribute + arrayl0..51 of string tl isis 
C Reed onty', *‘Hiaden',  *“Systen", “Votume 10%, 
‘oyrectory' ,o Ar entve: ttag?: 23 


var 
PAL SOTA Les Result, Attr : word; 
1 $s integer; Attrstriis ste tngtl 4d; 


procedure ReportError; 
begin 
case DosError of 
3s weitetn( ‘Dos: Error: :tavetid path’ 2; 
5: writeln( ‘Dos Error: file access denied' ); 
end; {case} 
end; 


begin 
clreers 
writeln(€ ParamStr(1) ); 
assign( Fil, ParamStr(1) ); 
GEtFASerC Pity ACS 2s 
if DosError <> 0 then ReportError else 
begin 
writeln(€ FExpand( ParamStr(1) ), 
‘Str Pete Dy te a fp MEER: 
1F 7A <<) Uther 
begin 
writet "Attripuete Fisage set are ” >; 
Tor :328 0 to: 3:00 
1F AGC and 4 BO - shit. +. 3042- 0 then 
writet ACErVGurentss 9" Oy 
end; 
end; 
writeln; 
writelnt: ‘Valid -Fi le attributes eres 2: 
writeln(€ '$01 = Read Only $04 = System' ); 
writeln(€ '$02 = Hidden $20 = Archive' ); 
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write( ‘Enter new attribute code ', 
"Chex format suggested): ' ); 

readint Attrstr 3; 

ValG BEtreStr.” Attra. ReSete 323 

if Result = O then 


begin 
Attr := Attr and AnyFile; 
1f Attr <> 0 then writet ‘New file attributes are * ) 


else write( ‘Attribute byte cleared ' ); 
for 1 t= 0 to 5 do 
if Attr and ¢€ $01 shl i ) <> O then 
writet Attributelitd,:* * 23 
writeln; 
SetFAttr<t' Fit. Attr 2s 


end; 
if DosError <> 0 then ReporteError; 
readln; 
end. 
{zseessesssesesseseeasaa } 
{ Read_Dir.PAS } 
{ reads and displays' } 


oa 


the disk: @dinectory a 


Uses Crt, vos? 


type 
STR8O = stringl80J; 


function Pad( Value: word ): string; 


var 
TempStrs: stringl2di; 
begin 
str( Value:2d, TempStr 23 
1f Tewmpstrlidt.=-* * hen Fesastroii-: e= 'O"s 
Pad := TempStr; 
end; 


function Format( Value: Longint 2: strings 
var 

Tempstr: atring; 

+ $$. thteger? 
begin 

str( Value:10, TempStr 2; 

14m 73 
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repeat 
eP FOMRS tris. <9. 4.3! 
Then ine@ert C42. Teme ste Tet 9 
Setse inserté ty Tempstr sg ths 
Geet 4554323 
UntT eS Os 
Format := TempStr; 
end; 


procedure WriteListing( DirItem: SearchRec ); 
const 

AtteStr se arrevyl0..33c°et @etringesas:: = 

( i Sl a gem ne Vot* | ‘Dirt, ‘A! ; 

var 

i: integer; FileDate : DateTime; 

Cte Peer str: 

FileName : NameStr; 

FileExt Yr EXtster) 


begin 
with DirItem do 
begin 
UnpackTime( Time, FileDate ); 
FSplitt Name, Dir, FileName, FIileExt ); 
write( FileName ); 
gotoxyt. 9, WhereyY d; writet FiteExt )>; 
1) ACtr <> OO: then 
begin 
BoTrOoxy.. 13, “Wherey 22 wrettett <1): 
ToC. 2a te-3. 40 
We Atte ene: © SOT snl 1.2.48 then 
write (APEretr’ tacks 
qotoxy( 20, (‘Wherey 322 wrt tet Ce os 
end; 
gotoxyt 21, Waerey-O; 
if Attr and (VolumelID+Directory) = O then 
weite( Format¢ Size = 2 ‘2d? 
gotoxy( 38, WhereyY ); 
with FileDate do 
write Month:2, '/', Pad(daey), ‘'/', PadtYear-1900), 
: ', Reese Me Pad thing; 43s 42s Pee tiee) > 2s 
end; 
writeln; delay( 1000 ); 
end; 


procedure ReadDirectory( PathSpec: PathStr; 
Attributes pyte 3 
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var 
Dirinfo : SearchRec; 
Entrien, Dircnt, Fitletnt, BackUs =: word 


begin 
PathSpec := FExpand( PathSpec ); 
Entries’ :=.02 DirCnt := OQ; 


File¢nt s= 0; BackUp := QO; 
writetnt "directory ‘search for *, PatnhsSpec )>: 
FindFirst¢ PathSpec, Attribute, .oOtrinto 2; 
if DosError <> O then wrttetnt *"* No Files *" ) else 
while DosError = 0 do 
begin 
WriteListing( DirInfo ); 
inet Entries 7; 
With DIPFinte:- doe 
if Attr and Directory = Directory then 
inct.Birent ) else 
if Attr and VolumeID <> VolumeID then 
begin 
HOt: EL LECHt: J 
if Attr and Archive <> O then inc BackUp ); 
end; 
FindNext( DirInfo ); 
end; 
gotoxy( 10, WhereY ); 
writetnc'* * * end of Directory Listing *:.7 4"? 
writeln; 
writetnt "Found *, Entries, ' total ‘bis tines metching *, 
PathSpec ); 
vritetac ‘This >ivacluces:*, Dirtnt, *“ Girectories and ', 
Piet ety oC tle .eee™ Ji 
if BackUp <> O then 
writeln( ‘Of these, ', BackUp, 
' files have not been backed up.' ); 


end; 


begin {main} 
TextAttr := $OF; 
cirscer; 
ReadDirectory( '*.*', AnyFile J; 
readln; 
end. 


, Mh atetntee BS hk 
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Chapter 12 


Creating Text Displays 


Text output was introduced back in Chapter 7 under the topic of manipulating 
numbers, because formatting number displays is an integral part of dealing with 
numerical values. But this is only one small part of creating text displays. In this 
chapter, text displays are the principal topic. 

Creating text displays involves a lot more than simply writing text to the screen. 
Tasks and procedures required for text display include color handling (or using 
inverse color if your display is monochrome), positioning and erasing text, using 
the extended ASCII character set, and managing text windows and text display 
modes. 

Before we get into the details of creating text displays, however, we need to take 
a look at the CRT unit itself. 


The CRT Unit 


Because Turbo Pascal is a compiler designed for all types of applications, groups 
of features have been created in the form of units. A unit can be used—via the uses 
statement, as we have seen—in applications that need the features it contains and 
omitted by applications that do not need those features. 

The reasons for this approach are simple. First, if all of the resources supplied 
by Turbo Pascal were included as part of the standard library, the TURBO.TPL 
library file would be rather unwieldy, particularly for programmers using floppy 
disks rather than hard disks. 
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Second, access time during compile would be too slow. While Turbo Pascal uses 
a smart linker, which includes only those library elements actually needed by a 
program, searching for specific features would still be slowed if everything were 
kept in a single unit. Ina sense, the unit approach is structured programming from 
the compiler’s viewpoint, organizing program resources in a form that minimizes 
location and access times. 

The CRT unit is the source library for Turbo Pascal’s screen display features. In 
this chapter, we will use it in most every program, if for no other reason than to 
access the ClrScr procedure, which allows the demo programs to begin with a clean 
screen each time. 

Programs that execute any type of screen display without using the CRT unit 
send their screen output through normal DOS channels. But this adds a fair bit of 
overhead to the display process. When the CRT unit is used without any special 
instructions from the programmer, text output is sent directly to the BIOS, not to 
DOS—or, providing even faster output, directly to the video memory. 

Here is how it happens: when the CRT unit is used, the Input and Output 
standard text files are linked to the CRT instead of to DOS’s standard input and 
output file. This is the equivalent of the following program instructions being 
executed at the beginning of a program: 


Asstontrt¢ input): 
Reset( Input ); 
AsstTGnCrCC outPut 23 
Reset( Output ); 


This reassignment also means that DOS I/O redirection of the input and output 
files is disabled unless they are explicitly reassigned to standard input and output, 
thus: 


Aséiont: taeut,; "23 
Reset( Input ); 
Asstant Qetput > .°%:. 7y 


Rewrite( Output ); 


There is one other limitation: the CRT unit can only be used with programs 
running on PC, XT, AT, PS/2 or compatible machines. This does not eliminate 
brand-name or trade-marked systems, however, because most ‘clones’ are 100% 
compatible, or sometimes more so. In the rare circumstance that your machine is 
not compatible, you should already have noticed this limitation while executing 
the Install program. 
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Aside from the increased screen output speed, there are a host of other reasons 
for using the CRT unit. In this chapter, the CRT unit is the source of all of the features 
discussed. 


Text Display Modes 


Normally, the computer is thought of as having only one text mode, with mode 
switching limited to graphics applications. This is not, however, correct. Though 
most applications never have any reason for changing text modes, alternative 
modes are available and might, occasionally, be useful. But you must understand 
how to use them and what limitations apply. 

The video modes listed in Table 12-1 are supported by predefined mode 
constants in Turbo Pascal. 


Table 12-1: Video Modes 
Constant Value Video Cards Limits 


BW40 0 CGA/EGA/VGA 40x25 B/W 

C040 1 CGA/EGA/VGA 40x25 4 color palettes 
BW80 2 CGA/EGA/VGA 80x25 B/W 

C080 3 CGA/EGA/VGA 80x25 16 colors 

Mono 7 Monochrome Adapter 80x25 B/W 

Font8x8 256 EGA/VGA 80x43 or 80x50 16 colors 
C40 1 Equals C040 for Turbo Pascal 3.0 compatibility 
C80 3 Equals C080 for Turbo Pascal 3.0 compatibility 
LastMode var Current or last active text mode 


Modes 0..3 are standard for most video adapters. Mode 7, however, is only 
compatible with monochrome video adapters and may cause CGA/EGA/VGA 
adapters to hang up. 

The font mode, Font8x8, is supported only by EGA/VGA video adapters. It is 
used not by itself, but in combination with one of the other five video modes to 
select the desired color settings and column widths. If Font8x8 is used alone, it is 
equivalent to calling Font8x8 + BW40 (256 + 0 ) and sets a black and white, 43- or 
50-line display with a 40-column width, which is a valid if not familiar video mode. 
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Setting Text Modes 


Setting a text mode is accomplished with the TextMode command, as in these 
examples: 


TextMode( C080 ); 
TextMode( Font8&x8 + C080 ); 


Each time TextMode is called, the CRT variable LastMode is updated with the 
new mode value. However, when a graphics mode is initiated, the LastMode value 
is not changed, allowing the previous text mode to be reinstated on exit from 
graphics mode. 

The demo program Vid_Test.PAS, which appears at the end of this chapter, 
demonstrates the several video mode displays. It may need to be adapted for your 
video adapter if you are using a monochrome or CGA system. To do so, simply 
comment out any tests that are not compatible. 


Setting Screen Positions 


While most applications have little need to change text display modes, positioning 
text on the screen is done extensively by a wide variety of applications. In limited 
forms, you have seen it done in some previous examples. 

The position of text on the screen is usually determined by the position of the 
cursor. Therefore, the GoToXY procedure, which positions the cursor, is an impor- 
tant one. 

The GotoXY procedure is called with two parameters specifying the x- and 
y-axis coordinates where the cursor will be positioned. Note, however, that these 
coordinates are window-relative, with (1,1) corresponding to the upper left corner 
of the active window. If no window is active, the entire screen is considered the 
active window. 

The gotoxy procedure is called as: 


Gotoxry< £5:° 723 


This positions the cursor at the x column and Y'" row of the active window, 
or of the screen if no window is active. 

Since text output to the screen using the write and writeln procedures always 
begins with the first character written at the current screen cursor position, the 
gotoxy procedure controls text positioning. 
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In fact, not only the first character of a string, but every character to output is 
written at the cursor position. However, after each character is written to the screen, 
the cursor position is moved either one column to the right, or if the cursor is at the 
right of the screen, down one row and to the first (left-most) column, ready for the 
next character to be written. 

To demonstrate both the gotoxy procedure and how characters are written to 
the cursor position, the demo program Hello2.PAS at the end of this chapter slows 
down what normally happens too fast for the eye to follow. 


Reading the Cursor Position 


Turbo Pascal, provides two functions, WhereX and WhereY, for determining the 
present x- and y-axis cursor positions. The WhereX and WhereY functions return 
window-relative coordinate values, reporting the first row or column of the win- 
dow or screen as 1. 

WhereX and WhereY can be called any time, but return only the cursor position 
at the time they are called. To save a pair of screen coordinates for later use, you 
must use two variables to hold their values until they are needed again, as shown 
in the Hello2.PAS demo program. 


Delaying Execution 


The Delay procedure provides a method of slowing down a program. It is called 
with a single parameter specifying a delay time in milliseconds. The delay proce- 
dure is called as: 


delay( timeout ); 


Timeout can be a variable or constant expression with a value from 0 (no delay) 
to 65,535 milliseconds ( = 65.5 seconds). The exact delay interval is an approxima- 
tion, not precise. For intervals longer than a few seconds, testing the elapsed time 
on the system clock is probably a better approach. 

During intervals specified by a delay instruction, no other instructions can be 
executed, though screen updates, cursor blinks and audio output from the internal 
speaker are not interrupted. 

The delay procedure is used in the Hello2.PAS program to slow down program 
execution between selected steps. You can adjust execution speed in this demo 
program by varying the timeout value. In the earlier demo program, Life.PAS, the 
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delay procedure was also used to control execution speed. In that instance, speed 
was controlled by changing a variable value in response to keyboard events. 


Display Editing 


Turbo Pascal provides features for editing an existing text display. These include 
the ClrScr procedure to erase a screen or window, the ClrEol procedure to erase to 
the end of a line, the DelLine procedure to delete a line, and the InsLine procedure 
to add a line within a display. 


CirScr 


The ClrScr procedure erases the entire screen or active window, setting all screen 
character bytes to spaces (20h) and all character attribute bytes to the current 
TextAttr color settings (see “Color Displays,” later in this chapter). 

When an active window setting is in effect, only the window area is affected by 
the ClrScr instruction. 

ClrScr is called without parameters. It is demonstrated in most of the preceding 
example programs, as well as in Window.PAS at the end of this chapter. 


DelLine 


The DelLine procedure deletes the entire screen line at the cursor position, scrolling 
all lower lines up and adding a blank line at the bottom of the screen. The new 
(blank) line is created using the current TextAttr color settings. 

When an active window setting is in effect, the DelLine instruction does not 
affect the display outside of the current window limits, and the new (blank) line 
created is at the bottom of the window, not the bottom of the screen, unless the two 
coincide. 

DelLine is called without parameters. It is demonstrated in the Window.PAS 
program at the end of this chapter.. 


InsLine 


The InsLine procedure inserts a new line at the cursor position, scrolling all display 
lines, including the line where the cursor appears, down one row. The new line 
inserted is blank and is created using the current TextAttr color settings. 

When an active window setting is in effect, the InsLine instruction is limited to 
the area of the active window, and any text display scrolled down beyond the 
window bottom is lost. Text display below the window is not affected. 
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InsLine is called without parameters. It is demonstrated in the Window.PAS 
program at the end of this chapter. 


ClrEol 


The ClrEol procedure erases the text display from the current cursor position to the 
end of the present line by setting all character positions to blanks, using the current 
TextAttr color settings. 

When an active window setting is in effect, the ClrEol instruction does not affect 
the display beyond the right window margin. 

ClrEol is called without parameters. It is demonstrated in the Window.PAS 
program at the end of this chapter. 


Text Windows 


Text windows are a convenient means of organizing screen displays without need 
of elaborate protections to prevent other parts of the screen from being affected. 
Within the limits set for an active window, any type of screen activity using the 
procedures supplied by Turbo Pascal can be carried out without affecting the rest 
of the screen. 

Thus, ClrScr, Write, ClrEol, InsLine and other CRT screen procedures are 
restricted in operation to the active window limits. By default, if no window limits 
have been established, the entire screen is the active window. 


Window Limits 


An active text window is established by calling the window procedure with four 
parameters specifying the upper-left and lower-right x- and y-axis window limits: 


wonduwt BULA, wer, rks -kr¥ 3: 


Text window coordinates begin with (1,1) at the upper left corner of the screen 
and extend to (80,25) at the lower right corner of the screen in the Mono, BW80 or 
CO80 text modes. On EGA/VGA systems, using the Font8x8 setting, the lower 
y-axis limits are 43 or 50. Using the BW40 or CO40 text modes, the x-axis limit is 40. 

Two restrictions apply to the calling parameters. First, all calling parameters 
passed to the window procedure must be within the valid range for the screen 
display. Second, the coordinates for the lower-right corner must be greater than the 
coordinates for the upper-left corner. If either of these restrictions is not met, the 
current window settings remain unchanged. 
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Displaying Multiple Windows 


While multiple screen windows can be created, Turbo Pascal’s window procedure 
is a primitive window operation, restricted to setting screen limits for screen I/O 
operations. Because of this, only one window exists at any time and no inherent 
procedures exist either to save screen images belonging to a particular window or 
to prevent one window from overwriting the information output in another. 

The Window.PAS demo program found at the end of this chapter illustrates the 
window procedure by creating four screen windows (see Figure 12-1). It then 
demonstrates the clrscr, write, gotoxy, insline, delline and clreol procedures within 
each of these windows. 


Figure 12-1: Four Text Windows 
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Window.PAS also illustrates how conflicts can occur between separate window 
displays, using windows 2 and 4, which partially overlap. The conflicts are shown 
in Figures 12-2 and 12-3. 

Later in this book, a window object is demonstrated, complete with methods 
and capabilities that prevent this type of conflict by saving and restoring the screen 
information belonging to each window. For the present, however, when using 
windows, an awareness of the potential problems and conflicts is your best defense. 
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Figure 12-2; Overlapping Window Conflicts 
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Figure 12-3: Overlapping Window Conflicts continued 
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Color Displays 


For color monitors, Window.PAS also demonstrates text color settings with random 
foreground and background color selections for each window. Before the InsLine 
procedure is called, the Invert function is used to swap the foreground and 
background color values, enhancing the display effects. 

Turbo Pascal provides two color setting procedures, TextColor and Text- 
Background, to assign foreground and background color values. Three additional 
procedures, HighVideo, NormVideo and LowVideo, respectively, select a high 
intensity display, restore the entry video setting and select a low intensity display. 


Text Color Information 


Text mode screen colors are controlled by the TextAttr variable which contains the 
current foreground, background and blink color values. This value is usually set 
by calls to the TextMode and TextBackground procedures, but values can also be 
assigned directly. 

In text modes on CGA, EGA or VGA systems, with or without a color monitor, 
the video system stores two bytes for each character position on the screen, one for 
the character value and one for the video attribute. This allows each screen character 
displayed to have an individual color assignment and, optionally, to have the blink 
bit set, causing the character to blink continuously. 

Normally, as each character is written to the screen, the current TextAttr value 
is also written as the color attribute for that character. It is possible, however, to 
change the color byte for a screen position without rewriting the character value, 
and vice versa. 3 

Color information is a one-byte value encoded in TextAttr, as shown in Figure 
12-4. | 

Since the color attribute byte uses only three bits of information for the back- 
ground color, background colors are limited to the value range 0..7 defined as Black 
through LightGrey (see Table 12-2). For foreground colors, however, four bits are 
provided, which can hold a range of sixteen colors (0..15 or Oh..Fh). The remaining 
bit, bit 7, is commonly used as the ‘blink’ bit. If set, it causes the character displayed 
to blink continuously. 

However, the function of bit seven of the screen attribute byte can be toggled 
from blink to intensity, providing four bits of information for the background color 
value and allowing a full 16 background colors. Turbo Pascal (as with most other 
languages) does not provide an option to switch from blink to intensity, but an 
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interrupt call to interrupt 10h, function 10h, subfunction 03h enables blinking if the 
BL register is set to 01h or selects intensity if set to 00h. This feature will be 
demonstrated later. It is not valid on CGA video systems, only on EGA and VGA 
systems. 


Figure 12-4; Color Byte Organization 


Blink Background Foreground 
Bit Color Color 
Bit 7 4 3 2 1 
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In text modes, color displays are controlled by four bits of information in a 
system known by the acronym IRGB, short for: Intensity, Red, Green, Blue. The 
three colors refer to the three color guns used in color CRTs, both on computers and 
on your TV. For computers, color displays are digitally controlled, and the eight 
low-intensity colors are created by turning on various combinations of the RGB 
color guns. 

In Table 12-2, the color values are shown at the right as binary or bit values, 
with the relevant control bits shown in bold. Thus, Black, which has the control bits 
Q000, does not turn on any of the color guns, while Blue, bit value 0001, turns on 
the blue color gun; Green, bit value 0010, turns on the green color gun and Red, bit 
value 0100, turns on the red color gun. The remainder of the first eight colors are 
created as a combination of these three primaries. 

The ninth color, DarkGrey, has the bit value 1000, which turns on the intensity 
control, triggering a minimal emission from all three color guns even though their 
individual control bits are all zero. All of the high-intensity colors consist of the 
corresponding low-intensity colors plus the intensity control intensifying the basic 
color. 

For graphics modes, especially on VGA systems, this color explanation is 
something of a simplification and will be elaborated later. But for the moment, this 
should serve to show how these byte values are used as binary flags to produce a 
color display. 
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Table 12-2: Text Color Constants 


Constant Value 
Black 0 
Blue 1 
Green 2 
Cyan 3 
Red 4 
Magenta 5 
Brown 6 
LightGrey 7 
DarkGrey 8 
LightBlue 9 
LightGreen 10 
LightCyan 11 
LightRed 12 
LightMagenta 13 
Yellow 14 
White 18 
Blink 128 


Hex 
00h 
Olh 
02h 
03h 
04h 
05h 
06h 
O7h 
08h 
09h 
OAh 
OBh 
0Ch 
ODh 
OEh 
OFh 
80h 


N 
Ss 
On 
— 


OD. OO CO 3:O SOS: OC - 2:0 COO OO: * 
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0 
B 
0 
1 
0 
1 
0 
1 
0 
1 
0 
1 
0 
1 
0 
1 
0 
1 
0 


Bit Number 

Usage 

foreground / background 
foreground / background 
foreground/background 
foreground / background 
foreground/background 
foreground / background 
foreground / background 
foreground /background 
foreground only 
foreground only 
foreground only 
foreground only 
foreground only 
foreground only 
foreground only 
foreground only 

blink only 


The final value shown in Table 12-2 is the Blink constant, which is used to set 
the blink bit in the TextAttr value. 


The TextColor Procedure 


The TextColor procedure is used to set the foreground color selection. It is called 
with a single byte parameter which can be any of the 16 color constants (or the 


corresponding byte values). 


The Blink constant can be added to any of these color constants to set the blink 
flag in the TextAttr variable. Alternately, if any value greater than 15 (OFh) is used 
as the calling parameter, the blink flag is set. 


TextColor is called as in these examples: 


TextColor(¢ Blue 


a; 


TextColor( White + Blink ); 


TextColor( $8E ) 
TextCotorGc:13 2; 


. 
7 


Blue characters 
Blinking White 
Blinking Yellow 
Yellow 


"mT ee ce OE a 


All subsequent text output to the screen will be written using the new color 


setting. 


wwe we 
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TextColor does not affect the background color setting. 


The TextBackground Procedure 


The TextBackground procedure is used to set the background color selection using 
any of the first eight color constants listed in Table 12-2 or their corresponding byte 
values. Values outside of the range 0..7 are treated as the equivalent of Value and 
$07. TextBackground is called as in these examples: 


TextBackground( Green ); { dark green background } 
TextBackground( 7 ); { brown background color } 


The foreground color setting is not affected, nor is the blink flag. 


Selecting High and Low Intensity Colors 


You can also change foreground colors from low intensity to high, and vice versa, 
without assigning new color values, by using the HighVideo and LowVideo 
procedures. 

The HighVideo procedure sets the intensity bit in TextAttr, changing the 
foreground color setting from colors 0..7 (Black..LightGrey) to 8..15 (Dark- 
Grey..White). HighVideo is called without any parameters. 

The LowVideo procedure turns off the intensity bit in TextAttr, changing the 
foreground color setting from colors 8..15 (LightGrey..White) to 0..7 (Black..Light- 
Grey). LowVideo is also called without any parameters. 

Note: HighVideo and LowVideo do not affect the existing display colors, only 
new material written after TextAttr has been changed. 


Restoring Entry Color Settings 


Each time a program is executed, at startup, the text attribute at the cursor position 
is read from the screen and saved. The NormVideo procedure is called to reset 
TextAttr to this reserved value. NormVideo is called with no parameters. 


Setting TextAttr Directly 


In addition to using the video attribute procedures already discussed, you can 
assign the TextAttr variable a value directly or read the existing value directly, just 
as with any other variable. 
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When assigning TextAttr a direct value, the predefined color constants can still 
be used, except that the background color must be shifted left four places and 
ANDed with 70h to remove the intensity bit, if any. 

For example, both the following instructions set a white foreground and brown 
background with no blink bit: 


TextAttr := Brown shl 4 + White; 
FOXCATOUR. Se Phi tee: fC FeClew cent 8) end: S70: 32> 


For a more general handling, with BColor specifying the background color and 
FColor specifying the foreground color, the format would be: 


TextAter 8 it: SCotor sh 4) and 870 #:: Feetvors 


The demo program Window.PAS at the end of this chapter calls the function 
Invert with TextAttr as a parameter, which returns a new color attribute with the 
foreground and background colors reversed. The returned value, in Window.PAS, 
is used to set a new value for TextAttr: 


function Tavertt colors: 2 oyte')s byte: 
begin 
TAvert 28: ¢) € Cotors ent. 6: 7: end $70. 2 + 
CoC Colores snr 4 Fir SUS 7) > 
end; 


In this version, the foreground color in the returned parameter is always in the 
range 8..15 (high intensity colors), and any blink flag set is turned off. This specific 
version was used to show how the existing color bits can be swapped in the proper 
format. 


For a more general handling, however, a second version of Invert can be called 
as a procedure: 


procedure Invert( Color : byte ); 
var 
BlinkBit: byte; 
begin 
BlinkBit := Color and $80; 
Text¢Cotort Cotor. shr 4 +: BUinkByte.2;> 
TextBackground( Color ); 
if Color and $08 <> QO 
then HighVideo else LowVideo; 
end; 


Chapter 12: Creating Text Displays 217 


This version preserves the intensity bit on the foreground color even though 
the colors themselves are switched. The blink bit setting is also preserved. 


Crt Unit Flags and Variables 


In addition to the TextAttr variable, the Crt unit also declares seven other variables 
that are global to any applications using the unit. The remaining variables are 
defined in Table 12-3. 


Table 12-3: Crt Variables 








Variable Type Variable Type 
CheckBreak boolean CheckEOF boolean 
CheckSnow boolean DirectVideo boolean 
WindMin word Wind Max word 
LastMode ~ word 


The CheckBreak flag is True by default and enables Ctrl-Break checking. If 
Ctrl-Break is pressed, the program terminates when the next screen write is exe- 
cuted. When CheckBreak is False, pressing Ctrl-Break has no effect. 

Also, at run time, the Crt unit stores the existing Ctrl-Break interrupt vector in 
a global pointer variable called Savelnt1B. 

The CheckEOF flag is False by default. When it is enabled (True), pressing 
Ctrl-Z while reading a file assigned to the screen generates an end-of-file character. 

The DirectVideo flag enables or disables direct video memory access by the 
write and writeln statements. When it is enabled (True), screen output is allowed 
to write directly to the video memory. When it is disabled (False), all output 
characters are written through BIOS calls, a slower process. 

DirectVideo defaults to True when a program begins and after any calls to 
TextMode. 

The CheckSnow flag enables and disables “snow-checking” when direct video 
writes are being executed. This is relevant primarily for CGA systems, where 
interference (snow) may result from video write operations outside of the horizon- 
tal retrace interval. Most monochrome and EGA systems are not affected, and VGA 
systems should never be affected. 

CheckSnow is set to True when color text modes are selected, restricting direct 
video output to horizontal retrace intervals. Snow checking may be disabled by 
setting CheckSnow to False at the beginning of a program and after each call to 
TextMode. 


218 USING TURBO PASCAL 6.0 





When DirectVideo is disabled, CheckSnow has no effect. 

The LastMode variable stores the last active text video mode and is used after 
exiting graphics operations to restore the previous text video mode. LastMode is 
set when a program begins and when each call is made to TextMode. It is demon- 
strated in the Vid_Test.PAS program at the end of this chapter. 


Window Limit Settings 


The WindMin and WindMax variables store the screen coordinates for the current 
(active) window. If no windows are active, WindMin is 0, while the WindMax word 
variable contains the maximum x- and y-axis values for the current screen mode as 
the low and high bytes. 

In each case, the x-axis value is extracted as a byte value as lo( Wind Min ) or lo 
( WindMax ), and the y-axis value is extracted as hi( WindMin ) or hi( WindMax ). 

Coordinates for an 80- by 25-character screen begin as (0,0) at the upper left 
corner and (79,24) at the lower right corner. However, coordinates passed to the 
gotoxy or window procedures begin by specifying the upper left corner with the 
coordinates (1,1), a one column or one row offset from the actual values stored in 
the WindMin and WindMax Crt variables. 


Writing Non-Keyboard Characters 


The complete ASCII character set (extended) supplies 256 character codes (0..255), 
of which 250 have printable screen characters. While there is no corresponding 
displayed bitmap, the space (20h) character is included in the printing characters. 
The non-printing characters consist of the null (OOh), bell (07h), back space (08h), 
line feed (OAh) and carriage return (ODh) characters and the undefined FFh char- 
acter. 

Except for the null and FFh characters, the non-printing characters can be 
included in output strings, and each affects the screen display in an appropriate 
manner as suggested by their names. 

The bell character (07h) does not print but sounds the internal speaker for 
approximately 500 milliseconds. While the bell is being sounded, no other display 
can be written. 

The backspace character (08h) moves the cursor back one character position, 
causing the preceding character to be overwritten by the next character. 

The line feed character (0Ah) moves the cursor down one line on the screen, 
scrolling the screen if necessary. 
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The carriage return character (0Dh) moves the cursor to the first column of the 
screen or window, but it remains on the same line. 

The complete character set is shown in Figure 12-5 with the non-display 
characters indicated by dotted ‘x’s. 

The keyboard, however, provides only a subset of the complete extended ASCII 
character set, making it rather difficult to enter the extended characters by typing 
them in a program line. Some editors provide alternative methods to enter these 
extended character codes, and some TSR utilities can be used to select and ‘pop’ 
the appropriate codes into a listing, but these are not the only alternatives. 


Figure 12-5: The Extended ASCII Character Set 
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Pascal permits any character to be specified by character code, using either 
decimal or hexadecimal formats, as shown in Table 12-4. 


Table 12-4: Alternate Character Entry Forms 





Char Decimal Hexadecimal Decimal Hexadecimal 
A chr(65) chr($41) #65 #$41 
A chr(146) ~=chr($92) #146 #$92 


£ chr(156) ~— chr($9C) #156 #$9C 
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Any of these formats can be used in program instructions and might appear 
thus: 


ThisStr := 'This string uses the ' + chr($92) + 
enepadeters 
wrettet (letetl’ eo) °FS9C,: FPounde, or >: tes): Yen. 2d: 


To create a character string to use for drawing screen boxes, you might define 
the string as: 


DBoxStr = #S$C9 + ASCD + ASBB + ASBA + #ASC8 + HSBC; 


This would assign six extended ASCII characters to the string variable DBoxStr. 

Warning: Not all printers support the extended ASCII character set. Consult 
your printer manual for support and instructions before attempting to output 
non-alphabetical characters to a hardcopy device. 


Special Effects 


The Crt unit supplies two additional functions, which might, at first, sound rather 
out of place: the Sound and NoSound procedures. However, since the Crt unit is 
the ‘catch-all’ for console facilities, this is the natural location for these two proce- 
dures. 

The computer’s internal speaker system is not especially sophisticated. Provis- 
ions for controlling the speaker are limited to turning the sound on with a specified 
frequency and turning it off again. But since the internal speaker is usually a cheap, 
2” diameter unit (or smaller), expecting much in the way of high fidelity would be 
pretty silly. 

Add-in cards are available that are capable of providing a much wider range 
of sounds, complete with complex wave forms, high fidelity and instrument voices, 
but these also have their own handling and, often, their own command languages. 

Still, even within the limitations of the internal speaker and the Sound and 
NoSound procedures, a variety of effects are still possible, as demonstrated by the 
SoundEff.PAS demo program at the end of this chapter. 

Used judiciously, sound effects can be valid attention-getting devices, warning 
the user of something that needs prompt attention. Overuse of these effects, 
however, can also be irritating. 
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Sound Procedure’ Crt 


The Sound procedure turns on the internal speaker. 
Declaration: Sound( Hz: word ); 


Hz specifies the frequency of the sound generated. The speaker continues to 
sound the requested note until explicitly turned off by a call to NoSound or until 
another call to Sound requests a change in frequency. 

Since Hz can only be integer values, fine tuning of frequencies to the musical 
scale is not possible. 


See also: NoSound 
Example: See SoundEff.PAS at the end of this chapter. 


NoSound Procedure’ (Crt 


The NoSound procedure turns off the internal speaker. 


Declaration: NoSound; 
See also: Sound 
Example: See SoundEff.PAS at the end of this chapter. 


Summary 


In this chapter, the CRT unit and screen output routines have been the principal 
topic, including screen positioning and windows. Color displays have also been 
discussed, together with a brief introduction to including non-keyboard characters 
in strings or writing them directly to the screen. 

In addition to writing to the screen, it is also useful at times to be able to read 
the screen—in the sense of reading the screen from the inside, not the outside. While 
this capability is not supported by any of the Turbo Pascal library functions, it will 
be featured in Chapter 15, by the creation of a custom function using an interrupt 
call. 

But before tackling customizations, several other areas where support is 
already provided need to be understood. Chapter 13, covers the remaining func- 
tions and procedures in the CRT unit, while in Chapter 14, they are used to create 
the newest version of the Check program with edited input fields and both visual 
and audio prompts. 


222 USING TURBO PASCAL 6.0 





fexsss2eteesnectaectertsreeecrcazeceaescse2e) 
{ Vid _Test.PAS } 
{ demonstrates text video modes } 
({ezrscscsetcsesetsessseeersseeetsseesce==)} 


uses LP t: 


function ModeName( Mode: word ): string; 


var 
TempName : stringl201]; 
begin 
case( Mode and $OOOF ) of 
BW40: TempName := 'BW40'; C040: TempName := '‘'C040'; 
BW80: TempName := 'BW80O'; CO80: TempName := 'CO080'; 
Mono: TempName := ‘'Mono'; 
end; 
if Mode and Font8&x8 <> O then 
TempName := 'Font8x8 + " + TempName; 
ModeName := TempName; 
end; 
procedure Test_Mode( Mode: word ); 
var 
Ty ca 22 Sn teoer: 
begin 
write( 'Press Enter to select ', ModeName(Mode), 
eerie MOE eo tare 
readln; 
TextMode( Mode ); 
Tor 4°89 >to 's do 
begin 
TOP 4 ent i ta:.9:. de write cr. 3s 
writet 3.93 
end; 
writeln(€ ‘The current mode setting is ', 
ModeName(LastMode), ' (€ ', LastMode, ' ) ' ); 
writeln(€ ‘Screen height is ', hi€ WindMax )+1 ); 
writetn«( * Sereen width 18 *, lot WindmMax 2417: 22> 
end; 
begin 
Cl rsers 


weitetat “Your default Centry) video sode ts. *, 
ModeName(LastMode), ' (€ ', LastMode, ' ).'); 
writeln(€ "WARNING: some modes may not be compatible with 
all video cards!" )->s 
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Test_Mode( BW40 ); 
Test_Mode( C040 ); 
Test_Mode( BW80 ); 
Test_Mode( C080 ); 
(* 
Test_Mode( Mono ); { may cause hang-ups, for } 
Test_Mode( Font8x8 + Mono ); { monochrome adapters only } 
*) 
Test_Mode( Font8&x8 + BW40 ); 
Test_Mode( Font8&x8 + C040 ); 
Test_Mode( Font8&x8 + BW80 ); 
Test_Mode( Font8&x8 + C080 ); 
writeln; 
write( ‘Press Enter to terminate test ' ); 
readln; 
end. 
(Sst SSeeSSSeeSeessesrersssssessssezresce=} 
{ Hello2.PAS } 
{ demonstrates the GotoxXY procedure, } 
{ the WhereX and WhereY functions and } 
{ text output at the cursor position } 
(SSSSSSsSSSSSSSetesesseessessseseszzrezes=} 
uses Crt; 
const 
Time = 20; { time delay in milliseconds } 
var 


1, Jj» Curx, Curt: tntvger- 
HetlloStr : string? 


begin 

HelloStr := ‘Hello, world!'; 

celLrse.cr:; 

for 7 s= 9 to 20 .do 

begin 
gotoxyt 73, 7 33 
CurY := WhereY; { get y-axis position } 
for j = 1 to ord( HelloStrli0d 2:-do 
begin 


get x-axis position 
write one character 
reposition cursor 

delay for visual effect 


CurX := WhereXx; 
write Heltostreid: 2: 
gotoxy< Curk, Cure >> 
delay( Time ); 


AAAA 
Wwe wy 
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gotoxy : Cork+t,: ‘Cury 2; 


delay( Time ); 





{ move cursor right 


} 


{ delay for visual effect } 


Window.PAS 


screen editing procedures and 


{ } 
{ demonstrates window operations, } 
{ } 
{ } 


text color settings 


Wink, WIRY 15=Winke> Winid, Colors : byte; 


(s===5=S=s225==5===- 
uses Crt; 
type 
WindRec = record 
end; 
var 


i: integer; 


WRec : arrayl1..6] of WindRec; 


function idnvertt Colors: byte 2: Byte; 


begin 
Tavert. +2 0 .¢ Colors srt: 6:9 
Cf Cetere shred 


end; 


procedure SetColors; 
begin 
if LastMode = C080 then 
begin 
TextColor( random(8)+8 ); 
TextBackground( random(8) 
end else HighVideo; 
end; 


procedure CreateWindow( WinNum, 
begin 
with WRecC WinNum J do 
begin 
SetColors; 
Colors := TextAttr; 


and $70 ) + 
or’ ° G08): 


{ returns 
b ES { returns 


Rigs, Ree Ne eS: 2; 


WIRKT se KTs WinYTi t= YT? 


WinX2 := X2; WinY2 
Window WinX1, WinY1, 
ctrscr, 

end; 


NormVideo; 
delay( 1000 ); 
end; 


procedure WriteWindow( WinNum 


var 
1.2. integer: 
begin 
with WReclC WinNum J] do 
begin 
TextAttr := Cotors: 
window( WinX1, WinY1, 
CLrsérs 
for 4 s@ 7 ta 30 ds 
begin 
write(C' This is 
delay( 100 ); 
end; 
end; 
NormVideo; 
end; 


procedure InsertNewLines( 
var 
i: integer; 


begin 
with WRecC WinNum J] do 
begin 
Textattr = 
Window(€ WinX1, WinY1, 
end; 
for = 1 te 3 do 
begin 
gotoxyt 2, 2 73 
InsLine; 
writet:."This ts an 
delay( 500 ); 
end; 
NormVideo; 
end; 


procedure DeleteTopLine( WinNum 


window #', 


WinNum 
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>= Y2; 

WiINnkz, MInY!: 3 
byte ); 

WinX2, WinY2 ); 


WinNum ); 


byte ); 


Invert<, Colors 


Winkd,s Wintd-2¢ 


insertion’: 2} 


bYtecUs 
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var 
Lor: tneeger > 
begin 
with WRecC WinNum J] do 
begin 
TextAttr := Colors; 
window( WinX1, WinY1, WinX2, WinYe2 
end; 
Tee 4: 8 oF fo 8 eo 
begin 
Cot eey Pog ae bos 
DelLine; 
detayt 500 )-; 
end; 
NormVideo; 
end; 
procedure ClearToEnd( WinNum: byte ); 
var 
1 tnteger's 
begin 
with WRecC WinNum J] do 
begin 
TextAttr := Colors; 
window( WinX1, WinY1, WinX2, WinY2 
end; 
FOR ea Be 3 ao 
begin 
gotoxuyt( 5, t¥2>%¢% 
ClreEol; 
delay( 1000 ); 
write('<Erased>'); 
end; 
NormVideo; 
end; 
begin 
clreer; 
randomize; 
wWinegout 4}: 1, 60, 259 2. 


for 1°22. 1: to 3999 do writet’.. 
CreasteWwindowt 1, 5, . 2, 49, 

Crestevingout 2, 35,0115  f3,::2 
Createvindowt 3, 103° 11, 305 2 


TUL 





(80x25) screen } 


CreateWindow ( 


for 1 = 1 to 
for 1 = 1 6 
for i := 1 to 
for 7 = 1 to 
readln; 


NormVideo; 
window’ 1, 1, 
cL Prscr 5 

end. 


uses Crt; 
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i; DER oe Pee, 1a 2g 

4 do WriteWindow( i ); 

4 do InsertNewLines( i ); 
4 do DeleteTopLine( i ); 
4 do ClearToEnd( i ); 


{ reset video attributes } 


0, £2 +3 { set full (80x25) screen } 
{ clean up screen } 

{sess Se S858 eSeR2eSe2zzz5=} 

{ SoundEff.PAS } 


{ demonstrates the Sound } 
{ and NoSound procedures } 


procedure SoundOn( Note, Tone, DelayLen: word ); 


begin 
Sound( Note * 
end; 


Tone @iv: 2 wy delay( DelayLen ); 


procedure SoundOff( DelayLen: word ); 


begin 


NoSound; delay( DelayLen ); 


end; 


procedure Alarm; 
var 

1: trteger; 
begin 


for i := 1 to 3 do 


begin 


SoundoOn€ 1000, 2, 300: 2; 


SoundOn( 
end; 
NoSound; 

end; 


procedure Beep; 
begin 
SoundOn( 440, 


S00, Tt, 200 2; 


Ee TOG: 2s NoSound; 
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end; 


procedure Boop; 
begin 

Sounqdtnt -220,: 2, 300 v3 NoSound; 
end; 


procedure Bell; 
begin 

sounde@n¢ 660, 1, 280::.2 3 NoSound; 
end; 


procedure Bounce; 


var 
1, 3}  Anteger; 
begin 
for +) #8: 7: downte 2 do 
begin 
Tor 3. t=: 500 to 700 do: ShuneGnt: 3, 1, 0°33 
SoundorttT¢..1. *%:° 30 23 
end; 
end; 


procedure BuzzSaw; 


var 
i: integer; 
begin 
for i := 500 downto 2 do 
begin 
Soundont: 14770, 143° 33 Souneott¢(: 3S: )> 
end; 
end; 


procedure Coin; 


var 
1°: tnteger; 
begin 
Tor: 3-28 20 downto: Ti: do 
begin 
SoundOn( 600, 3, 40-2; 
SoundOff(€ i*5+random(10) ); 
end; 
end; 


procedure Falling; 
var 
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1. ¢ trteger; 


begin 
for 1 s= 50 downto 20 do 
begin 
Seuncent 11g, 2, a0: 2 SoundorTrt 25 3; 
end; 
end; 


procedure MorseCode; 


var 
1 F integer; 
begin 
for i += 1 to 20 do 
begin 
SoundoOnt 600, 15: 100: 23 
SoundOff(€ 30+random(200) ); 
end; 
end; 


procedure Siren; 


var 
i: integer; 
begin 
for 7 22 200 to 2300 do’ SoaundGnat 1) 2], b= 23 
for { := 2300 downto 200: do Seunddnt 1, 2,::1- 33 
NoSound; 
end; 


procedure Woopie; 


var 
1 £ tnteger ? 
begin 
for: 4 = | ¢o° 7000 de Soundt 1 div 2 23 
for i s= 7000 downto 1 do Sound( i divi 2 3 
NoSound; 
end; 


procedure Zap( Key: integer ); 


var 
lo tx Keo dors aa teger: 
begin 
for 4 8 4 Fe:.7 3.80 
begin 


j <= | * 235 + € 51 - random: Key. 7 2; 
for k 2¢ 7 to 3 do 
begin 
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end; 


pro 
var 


beg 


end 


beg 
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Toro set Se Ste Kk Pe ae 
Seu oto awe oR eT eee eat we a 22 
delay( Key ); THEOL 2 eae 
end; 
end; 
NoSound; 


7 
cedure Combined; 


i: integer; 
in 
for: 1-28: 30 downto: 20. deo 
begin 
soungont 171.0, 35, 30 23 
soundott( ¢€5 ); 
end; 
tor +. $= 20 Ggownto 1. 4do 
begin 
Sounagn(. 200.33 40:22 
SoundOff(€ i*5+random(10) ); 
end; 


7 


in 
cirsecr; 
randomize; 
writeln(€ ‘This will demonstrate a ', 
"variety of possible sound effects' ); 
writeln; 


delay(1000); writeln( ‘Alarm' ); Alarm; 
delay(1000); writeln( 'Beep' ); Beep; 
delayt€1000); writetn( 'Bettl' dd Bell; 
delay(1000); writeln( 'Bounce' ); Bounce; 
delay(1000); writeln(€ 'BuzzSaw' ); BuzzSaw; 
Getay(10g00):  writetnt "Coin bolneing® 2: Coin: 
delays i0007;: writetnt 'Patlinge'® 2: Falling; 
delay(1000); writeln(€ ‘Morse Code' ); MorseCode; 
qdetey< 1000); writetnt:.*Stren’ 2); Siren; 
delay(1000); writeln(€ 'Woopie' ); Woopie; 
delay(1000); writeln( '‘Zap' ); Zap(30); 


delay(1000); writeln(€ ‘Combined effect: ', 
‘falling plus coin bouncing'); 
Combined; 


end. 
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Working with DOS 


Programmers frequently think of DOS as something they leave behind while their 
program is operating. This is, however, rather like trying to ignore the water while 
you’re swimming. Many of the operations executed by a program depend on the 
DOS environment for the actual processing. For example, almost all of the file 
operations demonstrated in Chapter 11 used interrupt calls to DOS functions for 
the actual handling. 

Chapter 14 demonstrates how to call DOS interrupt functions directly. In the 
meantime, however, a variety of DOS interactions are supported directly by Turbo 
Pascal that provide a number of useful features. In this chapter, we will take a look 
at them. 


Command Line Parameters 


One feature of the DOS environment that is widely used by application programs 
is the command line buffer, which allows a program to be called together with one 
or more entry parameters. This is one you probably use every time you operate 
your computer. 

For example, if you call your word processor with a text file specification to be 
edited, the file request is a command line parameter. If you load a spreadsheet with 
a data filename, you are using another command line parameter. Programs can 
even be called with several parameters consisting of one or more filenames, 
command line switches or other information. 


231 
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In this respect, DOS is quite flexible and allows almost anything. The only real 
restrictions are a maximum length of 127 characters on the command line and that 
command line parameters are delimited by either a space (20h) or a tab (09h) 
character. 

Before going further into handling considerations, however, we should take a 
look at the Turbo Pascal features that provide access to these parameters: 


ParamCount Function TURBO.TPL 


The ParamCount function reports the number of parameters passed to the program 
on the command line. 


Declaration: ParamCount: word 


ParamCount returns a word value reporting the number of parameters entered 
and assumes that each parameter is delimited by a blank or a tab character. The 
name of the program called is not included in the parameter count. 


See also: ParamStr 
Example: 
begin 
if ParamCount <> O then 
writeln€ ParamCount, ' parameters available’ 23 
else writeln(€ "No command Line parameters' ye 
end. 


ParamStr Function TURBO.TPL 
The ParamStr function is used to access a specific command line parameter. 
Declaration: ParamStr( Index: word ): string; 


If Index is less than or equal to ParamCount, ParamStr returns the Index'" 
parameter. If Index is greater than ParamCount, an empty string is returned. 

Under DOS 3.0 or later, an index value of 0 returns the drive / path/filename of 
the executing program. Under earlier DOS versions, an index of 0 returns an empty 
string. 


See also: ParamCount 
Example: 
uses Crt; 
var 
1 ¢ werd: 
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begin 
cirser; 
writeln( "Program name is: ', ParamStr( 0 ) ); 
for ji1.42 4 to ParamCount do 
wr Teetne sh" ee io Paramstre 4°39 x3 
readln; 
end. 


ParamStr returns only string values. It is up to the application to convert these 
to numerical values if necessary. 

You should keep in mind two additional considerations when using command 
line parameters: First, and most important, all command line variables should be 
read immediately on program entry and stored as variables within the application. 
The reason for this is that while the command line parameters may occupy up to 
127 bytes when a program is called, only the first 32 bytes of information are 
guaranteed to be available later. Read/write operations after the program starts 
may truncate the command line buffer to a default length of 32 bytes, possibly 
losing some information in the process. Granted, the first 32 bytes will be available 
indefinitely but it is still better programming to grab this information immediately. 

The second consideration is grouping information. For example, if the intention 
is to call an application with a series of filenames and with one or more flags for 
each to indicate desired operations, two different approaches are possible: either 
trying to decipher each parameter read in to decide if it is a filename or a command 
option, or grouping the filenames and command options to be read as groups of 
parameters. 

This latter approach might look something like this: 


myprog file1,pr,cpy file2,pr file3,dup,altfiles 
In this format, the first three parameter strings would be returned as: 


FILE2,PR,CPY 
FILE2,PR 
FILES,DUP,ALTELLES 

Note that, even though the parameter strings were entered as lowercase, the 
reported parameter strings are all uppercase, a conversion made automatically by 
DOS. 

Each of these strings could be subsequently deciphered as groups of instruc- 
tions: 
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FILE2 PR PY 
PELE? Pe 
PILES: See AETELLES 


As a last consideration, if your application is expecting three parameters from 
the command line, for example, an initial test should call ParamCount to find out 
how many actually exist. If ParamCount returns a value of 2, then instead of trying 
to read the third parameter, ask the user for it directly. 


Testing Command Line Parameters in the Turbo Pascal IDE 


Within the Turbo Pascal Integrated Development Environment, testing an applica- 
tion expecting command line parameters could be rather difficult, except that the 
IDE itself provides an option for supplying command line parameters when an 
application is executed. 

To enter command line parameters, select Run and Parameters from the menu 
bar to call a dialog box, as shown in Figure 13-1. 

In this example, a command line parameter list has been entered with nine 
parameters, which will be duly reported when ParmTest.PAS executes. 


Figure 13-1: Entering Command Line Parameters 


ile 






dit earch BRM ompile ebug ptions indow el; 
cc .PAS ii 

eos [Qe un Ctel-F9 | 

{ ENR RSRENSSSSRSS Program reset Ctr1l-FZ 

{ ParmTest .PAS | o to cursor F4 

{ demonstrates comman race into F7 


{ line parameters ... tep over Fa 
{<== seaba a Tacietann 


uses Crt; 





begin 
clrscr:; 
writeln saad enna . 
for i t= 1 to ParamCount do 
writeln( *(’, i, ’) *, ParamStr 
readin: 
end. 





Help Set command-line parameters to be passed to program 
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But this is not the only convenience provided here. The arrow at the right of the 
entry dialog box calls a history list of previous command line parameters, allowing 
a choice of calling parameters. 


System Date and Time 


Another area for program interaction with DOS is the system clock/calendar. Turbo 
Pascal provides support for both reading the date and time and, if desired, setting 
the system clock and calendar date. 


GetDate Procedure Dos 


The GetDate procedure returns the current date set in the operating system. 
Declaration: GetDate( var Year, Month, Day, DayOfWeek : word ); 


Values reported are in the ranges: Year 1980..2099, Month 1..12, Day 1..31 and 
DayOfWeek 0..6 with 0 corresponding to Sunday. 


See also: SetDate, GetTime, SetTime 


Example: 
uses Dos; 
const 
WeekDay : arraylO..6] of stringl9J] = 
C "Sunday". * Moriday*;: tuesday’, *Wednesday', 
"Thaursaay', ‘triday?t, 2 saturday’ ): 


var 
Day, Month, Year, WeekDay : word; 

begin 
GetDate( Year, Month, Day, WeekDay ); 
writeln(€ 'Today is ', WeekDay, ' °, Montes"; 

bay, “F"3 Yoar 33 
end. 
SetDate Procedure DOS 


The SetDate procedure sets a new date in the system clock. 
Declaration: SetDate( Year, Month, Day: word ); 


Valid parameter ranges are Year 1980..2099, Month 1..12 and Day 1..30. If the 
date requested is invalid, the instruction is ignored and the old calendar date 
remains in effect. 
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See also: GetDate, GetTime, SetTime 
Example: 
uses Dos; 
var 
Day, Month, Year : word; 
begin 
writec- Enter DAY): MONTH, YEAR? "23 
readln( Day, Month, Year ); 
SetDate(€ Year, Month, Day ); 
end. 


GetTime Procedure DOS 
The GetTime procedure returns the current time from the operating system clock. 
Declaration: GetTime( var Hour, Minute, Second, Sec100: word ); 


Value ranges reported are Hour 0..23, Minute 0..59, Second 0..59 and Sec100 
0..99. Note: Some system clocks only report in 2/ 100" of a second intervals. 


See also: SetTime, UnpackTime, GetDate, SetDate 
Example: 
uses Dos; 
var 
Houry Win, Sec, S$eci00 : word: 
begin 
GetTime(€ Hour, Min, Sec, Sec100 ); 
rT eetnt Time: new te ty Kher to oo BIN EES, 
See). *.:  o See ie sy 
end. 


SetTime Procedure DOS 
The SetTime procedure resets the system clock with a new time. 
Declaration: SetTime( Hour, Minute, Second, Secl100: word ); 


Valid ranges are Hour 0..23, Minute 0..59, Second 0..59, Sec100 0..99. If the time 
specified is invalid, the instruction is ignored. 


See also: GetTime, GetDate, SetDate 
Example: 
uses Dos; 
var 
Hour; Min, Sees word? 
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begin 
writet * Enter time as hh mm ss ' ); 
readtn( Hour, Min, See )>; 
SetTime€ Hour, Min, Sec, 0 D2 

end. 


In this example, the hundredths of seconds is simply zeroed, because even if 
you're tapping into WWV on shortwave (the national broadcast time standard), an 
integer second is as close as you're likely to get. Of course, if you want to calculate 
how many hundredths of a light second you’re distant from the WWV broadcast 
station, this can be entered as a constant. 


DOS Operations 


Turbo Pascal provides access to a variety of additional DOS features. Most or all of 
these are elements that are required only in unusual circumstances, but when they 
are needed, they’re invaluable. 


DosVersion Function DOS 


The DosVersion function returns the DOS version number. 
Declaration: DosVersion: word; 


DosVersion returns the DOS version number as a word value, with the major 
version number in the low byte and the minor version number in the high byte. 
Thus, DOS 3.30 returns 3 in the low byte and 30 in the high. 


Example: Also see Environ.PAS at the end of this chapter. 


uses Dos; 
begin 
writeln(€ 'This computer is operating under DOS version ', 
LoC DosVersion 2, *«*, WIC DosVersion ?; 
end. 


The primary reason for needing to know the DOS version number is when an 
application would like to use features supported by later versions—such as return- 
ing the application name as ParamStr(0)—but not available under earlier versions. 


DOS Environment Information 


Your AutoExec.BAT usually contains several environment specifications, such as: 
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COMSPEC=C:\DOS\COMMAND.COM 

PATH Ce NGERMSCrA\DOS sCs\HOTs Cs VEOUSE FCs \VABAT s Dc NEB sD: \WWy 
APPEND C:\DOS 

PROMPT $P $G 


Access to this information may be desired for several reasons. For example, an 
application might need to know such things as whether a specific directory path is 
included in the PATH environment string, where COMMAND.COM is located, or 
if some special conditions have been set. 

Whatever the reason, however, the EnvCount, EnvStr and GetEnv functions 
provide access to the environment settings, although they do not provide a means 
of altering the environment. 


EnvCount Function Dos 


The EnvCount function returns the number of strings contained in the DOS 
environment. 


Declaration: EnvCount: integer; 


Each environment string is in the form VAR=VALUE and can be examined 
using the EnvStr function. 


See also: EnvStr, GetEnv 


Example: Also see Environ.PAS at the end of this chapter. 
uses Dos; 


begin 


writtetnt. Found °, Envtount>: "environment strings:'. >; 
end. 


EnvStr Function DOS 
The EnvStr function returns a specified environment string. 
Declaration: EnvStr( Index: integer ): string 


EnvStr returns the environment string selected by the Index parameter, with 
the index of the first string as one. If Index is out of range (less than 1 or greater 
than EnvCount), EnvStr returns an empty string. 


See also: EnvCount, GetEnv 
Example: Also see Environ.PAS at the end of this chapter. 
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uses Dos; 
var 
1 2 Word? 


begin 
Tor t 27 te eEnveounta6 
WEN EOLAL 67> Tete | AMS SEO 2 
end. 


GetEnv Function DOS 


GetEnv returns the value of a specified environment string variable. 
Declaration: GetEnv( EnvVar: string ): string; 


The variable name is not case sensitive, i.e., may be upper or lower case, but 
must not include the equal sign character (=). If the requested environment variable 
does not exist, an empty string is returned. 


See also: 
Example: Also see Environ.PAS at the end of this chapter. 
uses. Crt, Dos; 


begin 
writeln(€ 'The current Path environment is:' ); 
writeln( GetEnv( ‘Path’ 2 2; 

end. 


Control-Break Interruptions 


One additional DOS element that can be checked and controlled by Turbo Pascal 
is Ctrl-Break checking. The DOS Ctrl-Break flag is a boolean control. When Ctrl- 
Break is True (on), DOS tests for a keyboard Ctrl-Break key event at every system 
call. Alternately, when Ctrl-Break is False (off), checks are made only during I/O 
to the console, printer or communication ports. 


GetCBreak Procedure DOS 
GetCBreak returns the state of Ctrl-Break checking in DOS. 


Declaration: GetCBreak( var Break: boolean ); 
See also: SetCBreak 
Example: See C_Break.PAS (Chapter 14) 
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SetCBreak Procedure Dos 
SetCBreak sets the state of Ctrl-Break checking in DOS. 


Declaration: SetCBreak( Break: boolean ); 
See also: GetCBreak 
Example: See C_Break.PAS (Chapter 14) 


Interrupt Vectors 


Ctrl-Break events are handled by DOS interrupt 23h, but for complete control over 
this key event, you can use interrupt 21h, function 25h to redirect Ctrl-Break 
checking to an internal handling routine. In this fashion, an application can assume 
its own Ctrl-Break handling and prevent being unexpectedly interrupted—which 
can be critical in certain applications. 

This will not, of course, prevent the user from switching off the power or 
pressing the reset button, but nothing is completely idiot proof. 

To gain control of a DOS interrupt such as interrupt 23h, Turbo Pascal’s 
GetIntVec, SetIntVec and SwapVectors procedures provide an alternative to writing 
complicated assembly language routines. This topic, however, is deferred to Chap- 
ter 14. 


Summary 


In this chapter, access to and use of DOS information has been the principal topic. 
While not all applications will need this type of access, awareness of these capabil- 
ities may make any number of applications easier to design and implement. 

In Chapter 14, further access to DOS interrupt functions and DOS features is 
demonstrated, including methods of gaining control of special resources that may 
be useful or even essential in specialized applications, but are not supported 
directly by Turbo Pascal routines. 


{sseSeeees5 232528 2e22= } 
{ ParmTest.PAS } 
{ demonstrates command } 
{ Line parameters: ss } 
{sz ksceezsersesesecse ees = =) 


uses Crt; 


var 
tt -werd: 
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begin 
cArsSser> 
writeln(€ ‘Program name is: ', ParamStr( O ) ); 
for 1 := 1 to ParamCount do 


COCOA AS oy as 82 tS Paramstrt<-1-9 33 
readln; 
end. 
{ssee2eeessesescesseszesezse2=z=} 
{ Environ.PAS } 


{ demonstrates access to } 
{ the DOS environment data } 


uses Crt, vos: 


var 
, £ werd: 


begin 
CAPSGr: 
writeln(€ ‘This computer is running under DOS version ', 
Lot DesVersion I, *.%, ere, Poesversion ) >: 
Wwriteln( ‘Found ', EnvCount, "environment strings:' ); 
for 1°s=. 1 to EnvCount do 
westetnt *<%, tT, "2.19 “ERnweeete 3s 
writeln; 
writeln(€ ‘The current Path environment is:' ); 
writeln( GetEnv( ‘Path’ >) )d; 
readln; 
end. 


WS Wives: 





Chapter 14 


Special Features and Custom Processes 


An old saying holds that “What you don’t know can’t hurt you.” This aphorism 
may or may not be true, depending on the circumstance. The following restatement 
of it, however, is particularly valid for programmers: “What you don’t know, can’t 
help you.” 

This chapter covers a number of features and provisions in Turbo Pascal, 
ignorance of which might not hurt you, but knowledge of which can, in many 
circumstances, be very helpful. 


Interrupting Programs 


The first two items are two methods of interrupting process or program execution. 
While neither of these is recommended for general use, and over-reliance on either 
would definitely be a sign of poor programming, there are circumstances where 
these can be, quite simply, invaluable. 


Exit Procedure TURBO.TPL 
The Exit procedure exits immediately from the current block. 
Declaration: Exit; 


The Exit procedure is generally used within a subroutine (a procedure or 
function), causing the subroutine to terminate immediately and return control to 
the calling process. The Exit procedure may also be called in the main program 
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block, causing the program to terminate, but this is considered bad programming 
practice. 


See also: Halt 


Example: 
uses Crt; 
var 
k Sn tegers 
Ch -2:¢haeez 
begin 
k := random( 10 ); 
writeln(€ ‘A random exit integer has been ', 
"chosen in the range 0..9' ); 
writeln(€ ‘ALL other characters will be echoed' ); 
repeat 
Ch := readkey; 
+t Ch = chert k 4-620" 3 then: exit 
else writet Ch +; 
until False; 
end. 


Since the test condition for the repeat loop until False; can never be satisfied, 
the loop will execute indefinitely, and the only way out is the exit procedure. 


Halt Procedure TURBO.TPL 


The Halt procedure immediately terminates program execution, returning control 
to the operating system or to a parent program. 


Declaration: Halt [| ( ExitCode: word ) |; 


ExitCode is an optional expression of type word specifying the program exit 
code. Calling Halt without a parameter is equivalent to Halt( 0 ). 

If control is returned to a parent process (see Parent.PAS and Child.PAS at the 
end of this chapter), the exit code can be examined by the parent process using the 
DosExitCode function. If control returns to DOS, an ERRORLEVEL test can be 
executed in a DOS batch file. 

Halt also initiates execution of any unit Exit procedures (see Chapter 18 in the 
Turbo Pascal Programmer’s Guide). 


See also: Exit, RunError 
Example: See Parent.PAS, Child.PAS at the end of this chapter. 
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RunError Procedure DOS 


The RunError procedure halts program execution, generating a run-time error 
message. 


Declaration: RunError [ ( ErrorCode: byte ) ]; 


The RunError procedure is similar to the Halt procedure, except that a run-time 
error is generated at the executed (current) statement. By default, an error code of 
0 is generated, or an optional error code can be specified by the program. 

The Runkrror procedure is useful while troubleshooting programs under the 
Turbo Pascal IDE with the Debug information option enabled. Within the IDE, 
RunError terminates execution, and the editor automatically positions the program 
at the point where RunError executed, just as if an ordinary run-time error had 
occurred. 

RunError is useful for testing special conditions within a program. Custom 
run-time error codes can be returned, for example, in the range 50..99, which is not 
currently used and has no built-in error messages. 


See also: Exit, Halt 


Example: 
uses Dos; 
var 
K © Integers Ch, S6hee: 
begin 
randomize; k := random( 10 ); 


writeln(€ ‘A random exit integer has been ', 
‘chosen itn thé: renoge. 8..9'..2:3 

writetn® "ALL other characters: witt be echoed’ ?); 
repeat 

Ch := readkey; 

1tT Gh <}- thet k + $30 2 then! writet “Ch 

else 

case k of 


O: Runtrrort.. 30...23 Lar RGnError(¢ 317: 2; 
2a: RunErrort: 52): as “RKinerror € 53-22 
és: Runberert-- 5464 =2's 32. Rene rTort oF 22 
6: Runerroreé 36°32 4%: Rontrror<-57 2; 
So: RUMNERrOrT: SS 23 9: “Runerror( S59 d> 


end; 
until False; 
end. 
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Executing Other Processes 


Turbo Pascal offers provisions that allow one program (parent) to call and execute 
another (child) program. This provision is frequently used for several related 
programs that may need to call each other in irregular order, or for menu processes 
that load and execute subprograms. 

A single parent program can call any number of child programs, which, unless 
very badly behaved, return control to the parent program. 

Two programs, titled appropriately Parent.PAS and Child.PAS, demonstrate 
this process later in this chapter, but first, two relevant subroutines need to be 
introduced: 


Exec Procedure DOS 


The Exec procedure executes a specified program, providing a specified command 
line input. 


Declaration: Exec( Program, CmdLine: string ); 


The Program parameter provides the drive/ path specification and the name of 
the program to be executed. The CmdLine string provides command line parame- 
ters. 

The child process can return an exit message to the parent process using the 
Halt procedure and recovered, by the parent, using the DosExitCode function. 

The SwapVectors procedure described below is called both before and after the 
Exec procedure. First, to ensure that the executed process does not use any interrupt 
handles installed by the parent process, and, second, to restore any interrupt 
handles used by the parent process. 

One other consideration is that enough memory needs to be available for the 
child process to execute—which requires reducing the amount of memory used by 
the parent process, by default, the maximum available heap. For this purpose, a 
memory allocation instruction is used: 


{$M $4000, 0, O } 


This allocates a 16K stack with no heap reserved or required, leaving most of 
the available memory free for use by the child process. The {$M directive is 
discussed further in Chapter 15. 
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See also: DosExitCode, SwapVectors 

Example: Also Parent.PAS, and Child.PAS at the end of this chapter. 
SwapVectors; 

exec Dirt" Child Exe". chr €i+$30) 3 
SwapVectors; 


DosExitCode Function DOS 


The DosExitCode function returns the exit code from a child process. 
Declaration: DosExitCode: word; 


The recovered error code is composed of two byte codes. The low byte is the 
code returned by the child process using the Halt procedure, while the high byte 
reports the method of termination as: 


0 normal termination 2 terminated by device error 
1 terminated by Ctrl-Break 3 terminated by Keep procedure 


See also: Exec, Keep 

Example: See Parent.PAS, and Child.PAS at the end of this chapter. 
SwapVectors Procedure DOS 

SwapVectors swaps interrupt vectors. 

Declaration: SwapVectors; 


The SwapVectors procedure swaps the contents of the SavelntXX pointers in 
the System unit with the current contents of the interrupt vectors. This is commonly 
called both before and after a call to Exec, ensuring that the executed child process 
does not use any interrupt handles that may have been installed by the parent 
process, and restoring the configuration expected by the parent process on return. 


See also: Exec 
Example: See Parent.PAS, and Child.PAS at the end of this chapter. 
Customizing DOS Interrupt Operations 


While Turbo Pascal provides procedures and functions for most purposes an 
application might require, you may occasionally wish to use other DOS interrupt 
calls to accomplish special tasks. 
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This could be accomplished using assembly language routines to create custom 
function libraries, but more conveniently, the Intr and MsDos procedures provide 
direct access. 

There is one restriction, however: Software interrupts that rely on specific 
values in the SP or SS registers on entry, or return values in the SP or SS registers, 
cannot be executed using the Intr or MsDos procedures. 


Intr Procedure DOS 
The Intr procedure is used to execute a specified DOS software interrupt. 
Declaration: Intr( IntNo: byte; var Regs: registers ); 


IntNo is the DOS interrupt requested (0..255) while registers is a record type 
defined in the DOS unit and illustrated in the example below. 


See also: MsDos 


MsDos_ Procedure DOS 
The MsDos procedure executes a DOS interrupt 21h function call. 
Declaration: MsDos( Regs: registers ); 

A call to MsDos is the same as a call to Intr with an IntNo of $21 (21h). 


See also: Intr 


Intel 80x86 Interrupts 


80x86 CPUs support three types of interrupts: internal hardware, external hard- 
ware and software interrupts. 


= Internal hardware interrupts. These are interrupts generated within the 
CPU by events during program execution—such as divide by zero 
attempts or overflow—and handled internally by the CPU. These are 
hardwired into the CPU and can not be modified or utilized by applica- 
tions. 

s External hardware interrupts. Interrupts triggered by external device con- 
trollers or coprocessors. Again, these are hardwired interrupts and can 
not be modified or utilized by applications. 
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« Software interrupts. Non-hardware interrupts loaded into memory on 
boot-up and used by application software to execute system specific 
tasks. Many interrupts in this last category are called by many existing 
program functions and procedures but all can be called directly by appli- 
cations as necessary. 


Software interrupts are further divided into two categories: BIOS and DOS 
interrupts. 


BIOS Interrupts 


BIOS interrupts are specific to individual computer systems and are contained as 
firmware in the ROM BIOS chips supplied by the hardware manufacturer. They 
provide hardware dependent drivers for the console and keyboard devices (CON), 
the line printer (PRN), auxiliary device (AUX), the system clock (CLOCK$) and the 
boo disk device. 

During system initialization (boot-up) the BIOS instructions are read into RAM 
as part of IO.SYS (IBMBIO.COM in PC-DOS). 


DOS Interrupts 


DOS interrupts are found in the MSDOS operating system (the DOS kernel) and 
include hardware-dependent services known as system functions. Interrupt services 
supplied include file and record management, memory management, device I/O, 
application execution and the real-time clock. 

Like the BIOS instructions, the DOS kernel is read into memory during system 
initialization from the MSDOS.SYS file (IBMDOS.COM in PC-DOS). 


Using the Intr and MsDos Procedures 


The Intr and MsDos procedures provide access not only to the MSDOS function 
library but also to processes in the ROM BIOS, to mouse driver functions and to 
EMS functions. Before jumping into this world of low-level functions, however, you 
should have a good reference guide that tells you what interrupt functions are 
available, how each is called, what limitations are applied and how information is 
returned. 

One recommendation would be Ray Duncan’s Advanced MS-DOS Program- 
ming, which, while written expressly for assembly language and C programmers, 
provides a comprehensive library reference to the DOS, BIOS and mouse function 
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calls. Alternately, a more concise set of references can be found in the titles: [BM 
ROM BIOS, MS-DOS Functions and MS-DOS Extensions, also by Ray Duncan. 

For demonstration purposes, the demo program GetEquip.PAS at the end of 
this chapter shows calls to ROM BIOS functions using the Intr procedure. Further 
examples appear in later chapters. 

Remember, use of the MsDos procedure is exactly the same as Intr, except that 
only interrupt 21h functions are called, and therefore, no function number is 
specified in the calling parameters, only the Regs parameter. 


The Registers Record Type 


The Registers record type is used to transfer data to the CPU registers to call 
interrupt functions and to return data resulting from the interrupt call. 

The CPU uses hardware registers—memory circuits internal to the CPU—to 
contain information relevant to requested instructions. And, after the instructions 
(interrupt functions) are completed, these same registers contain the operation 
results which, frequently, need to be returned to the calling application. 

Registers is defined in the DOS unit as: 
type 

Registers = record 
case integer of 
O2°'<) ANZ BX, CX, OX, BP SL, 02 OSES, Flags =: word 7; 
etc AL AR, BL, Ba, CL, CH bu ee: byte 23 
end; 


The Registers record type uses a case statement to define two variant record 
types, not because any selection will be made for one type or another, but so that 
two different sets of register identifiers can be referenced as needed. 

For example, the AX register is a word value, but the AL and AH registers are 
byte values, which are mapped to the same space as the AX register. In this fashion, 
the AX register can be referenced for the word value, or the AL register can be 
referenced for a byte value, which is the equivalent of referencing lo( AX ) while 
AH is the equivalent of hi( AX ) (see Figure 14-1). In like fashion, the BX register is 
overlaid by BL/BH, CX by CL/CH, and DX by DL/DH, while the remaining 
registers are accessed only as word values. 

Now, if it seems odd for the low byte to occur first and the high byte to occur 
second, this is a convention that was established by hardware requirements of early 
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systems—placing the /sb or least significant byte first and the msb or most significant 
byte second. 

The important factor, however, is that some interrupts will require or return 
values that need to be accessed as word values, while others will use byte values. 
Supplying both AX and AL/AH register variables simplifies access to these. 

Of course, there are always exceptions and one such exception is demonstrated 
in GetEquip.PAS at the end of this chapter. 


Figure 14-1: The Registers Record Type 





The Flags Register 


The Registers.Flags word value will contain several flag bits copied from the CPU 
flags register and resulting from the interrupt call. These flag values are named as 
Carry, Parity, Auxiliary, Zero, Sign and Overflow, but are often used for purposes 
other than the names might imply. Many interrupt calls may return special infor- 
mation in one or more flags. Turbo Pascal defines six flag constants for use in testing 
Flags information, as shown in Table 14-1. 


Table 14-1: Flag Constants 


Flag Bit # Flag Constant Constant Value Bit Value 

Carry OOh FCarry $0001 0000 0000 0000 0001 
Parity 02h FParity $0004 0000 0000 0000 0100 
Auxiliary 04h FAuxiliary $0010 0000 0000 0001 0000 
Zero 06h FZero $0040 0000 0000 0100 0000 
Sign 07h FSign $0080 0000 0000 1000 0000 
Overflow OCh FOverflow $0800 0000 1000 0000 0000 


Only six of sixteen flags are recognized here, since these are the only ones that 
will be used by interrupt calls to return flag information. 

Flag values are tested to determine if they are clear (0) or set (1). Several 
interrupt functions use the Carry flag to indicate that the desired interrupt opera- 
tion was successful, setting it if an error has occurred or clearing it if successful. 
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For example, if Regs is a register record, the Carry flag can be tested thus: 
if Regs.Flags and FCarry = 0 then 


If the Carry flag has been set, indicating an error, then subsequent instructions 
dealing with the returned register values can be skipped and an alternative 
response executed. 

Many interrupt calls, of course, do not return a success/ failure flag, or they 
return more complete information or values in some other form, either as word or 
byte register values, or as an address value (pointer address) in memory where a 
record or other data structure contains information. 

In the present examples, as in most interrupt functions, the returned informa- 
tion is reported in one or more registers. 


Calling the Interrupt 


Before the software interrupt call is executed, Intr pushes the CPU registers onto 
the stack and loads the CPU’s AX, BX, CX, DX, BP, SI, DI, DS, and ES registers from 
the Regs record. On return, the CPU’s registers are copied back to the Regs record 
and the original values are restored from the stack. 

GetEquip.PAS begins by calling ROM BIOS interrupt 11h to retrieve informa- 
tion about the computer hardware configuration. (Note: This interrupt is valid only 
for PCs (PC, XT and PCjr), ATs (PC/AT and PC/XT-286) and PS/2s (all models), 
compatibles included.) 

Interrupt 11h does not require any registers to be set before calling but returns 
several pieces of information in the AX register. The interrupt call is executed as: 


intr¢ $17, Ree@s:::)3 


After the interrupt call returns, the AX register is tested as bit values for several 
pieces of information, thus: 


« Bits 14-15 (OEh-OFh) contain the number of parallel (printer) ports. These 
two bits are tested as: 


DPrint >= AX shr $0E; 


« Bit 13 (ODh) is set, indicating two different pieces of information. For PCs 
and X'Ts only, if an internal modem is installed, or, for a PCjr, if a serial 
printer port is installed. 

« Bit 12 (OCh) is set if a game adapter is installed. 
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» Bits 9-11 (O9h-OBh) provide the number of serial (RS-232) ports installed 
(up to four ports). These three bits can be tested as: 


DSerial := € AX shr $09 ) and $07; 


= Bit 8 is reserved (undefined). 
« Bits 6-7 show the number of floppy drives installed, beginning with a 
value of 0 indicating 1 floppy drive. This is tested as: 


DFloppy = € (€ AX shr $06 ) and 304.3: 4:42 


« Bits 4-5 indicate the initial video mode—a good way of finding out 
whether the video is color or monochrome. The bit results are returned 
as: 

00—reserved (not used) 
01—40 by 25 color text 
10—80 by 25 color text 
11—80 by 25 monochrome 


Bits 4-5 are tested as: 
DVideo := (€ AX shr $04 ) and $03; 


« Bits 2-3 are used only by the original IBM PC with the 64K system board 
and by the PCjr. For PS/2 systems, bit 2 is set to indicate that a pointing 
device (mouse) is installed. 

« Bit 1 is set if a math coprocessor is installed. It is tested as: 


if © “AX cand S62 2. <> © 


« Bit 0 is set if at least one floppy disk drive is installed—a holdover from 
early systems where floppy drives were the exception and (shudder) cas- 
sette tapes were used for mass storage. 


Now, this interrupt call provides quite a bit of information about the system 
but deciphering the returned information is not automatic—which is one reason 
why a good reference source is suggested. A second reason will be apparent in a 
moment. 

ROM BIOS interrupt 11h (17) accomplished only one task but many interrupt 
calls have several functions, or, in some cases, subfunctions to functions. A good 
example is interrupt 13h (19), which provides disk controller services through 27 
separate functions. 
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GetEquip.PAS calls interrupt 13h, function 08h in two different contexts: first, 
to determine the type of floppy drive(s) installed and second, to test for and report 
on hard drive installations. 

While the interrupt number is passed in the call to Intr, the function request is 
passed by loading the Regs.AH register with the function number before Intr is 
called as shown below. If a subfunction specification is also required, this is loaded 
in the Regs.AL register. 


with Regs do 
begin 


AH := $08; { function O8h } 


In this instance, in addition to the function number, a drive specification is 
required to select the floppy drive or hard drive. And this information is passed in 
the Regs.DL register: 


DL := Drive; { drive number } 


intrt S435, Reqs 22 


The drive specification, for floppy drives, begins with 00h for drive A: and runs 
up to 7Fh (in theory at least). For hard drives, the drive specification begins with 
80h through FFh. Even though your hard drive is designated C:, it would be 
identified as 80h, the first hard drive. A second physical hard drive would be 81h, 
and so on. 

After the interrupt returns, the Carry flag is tested to determine if the interrupt 
function was successful—i.e., if the requested drive actually exists: 


1T FPiagse and FCarry = 0 then { test carry 


If the interrupt fails, returning with Flags set, additional error information is 
reported by the value in the AH register. But assuming the drive does exist, for 
floppy drives, the value returned in the Regs.BL register identifies one of four 
floppy drive types, as defined in Table 14-2. 


Table 14-2: Identifying Floppy Drive Types 


BL Floppy Drive Type BL Floppy Drive Type 
Olh 360K, 40 track, 5.25" 03h 720K, 80 track, 3.5" 
02h 1.2M, 80 track, 5.25" 04h 1.44M, 80 track, 3.5" 


Other information is available in the CH, CL, DH and DL registers, which will 
be shown in a moment, in determining the hard drive type. 


Taq? 
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To test for hard drive(s), interrupt 13h, function 08h is called as before, but the 
drive number is added to 80h before the interrupt is called: 


with Regs do 


begin 
AH := $08; C function Oh } 
DL := $80 + Drive; { hard drive inquiry } 
intr c. $13, Regs 23 { tnterrupt: 157 } 


On return, the information supplied is deciphered in a different fashion: 


if Flags and FCarry = O then { test carry flag } 
begin 
HDCnt := DL; 
The first piece of information is returned in Regs.DL and reports the number 
of physical hard drive units reported as the current drive. While not common today, 
in the past, two or more physical drives might be connected to act as a single hard 
drive unit. 


HDHead := DH+t+1; 


Regs.DH reports the maximum head number, but since heads are numbered 
beginning at 0, one is added to the report value here: 


HDSect := CL and $S5F; 


The CL register reports the maximum sector number, but only in bits 0..5. 
Therefore, the actual value is anded with 3Fh while bits 6..7 in CL are used as the 
most significant bits in another value. 


HOCyln- 22 CH we Ch CLeehese 24.8700 2 +. 1; 


The last piece of information is the hardest to decipher because it is a 10-bit, 
unsigned integer with the lower eight bits in the CH register and the two high bits 
derived from the CL register. 

This is deciphered by first shifting the CL register value left six bits, then 
multiplying it by 100h to move the remaining two bits left by the shift up to a high 
byte value before adding the 8-bits in the CH register, and finally adding one to get 
the cylinder count instead of the maximum cylinder number. 

At the same time, this particular interrupt has been surpassed by hardware 
developments because the largest value which can be reported by a 10-bit integer 
is 3FFh (1023), while many contemporary hard drives have higher cylinder counts. 
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Last, if the test on the Carry flag failed, the HDCnt variable is set to zero, 
indicating that no corresponding hard disk device was recognized: 


end else HDCnt := O; { drive not found 


In the GetEquip.PAS program at the end of this chapter, two different subrou- 
tines use interrupt 13h to test for floppy drive and hard drive information. For the 
floppy drives, the number of drive units is already known from the prior call to 
interrupt 11h, soa simple loop is enough. But for the hard drive(s), there is no ready 
information on how many hard drives, if any, are installed. Therefore, a different 
type of test loop is used: 

1223 Ge 
while Report HOC 1 ). do. inet 4°) 3 

In this particular loop, the test condition is itself the whole point of the loop, 
plus the need to increment the drive id (i) passed for the test. 

Figure 14-2 shows the report generated by GetEquip.PAS. The information 
shown is essentially correct, though not entirely. 


Figure 14-2: Equipment Report Generated by GetEquip.PAS 





Equipment list ... 
Parallel port(s): 1 
Serial port(s): 2 
86x87 coprocessor: not found 
Initial video mode: 88x25 Color 
Floppy drive(s): 2 
Floppy drive A: is 1.44M, 86 track, 3.5" 


Floppy drive B: is 1.2M, 8@ track, 5.25" 
Hard drive @: present as 1 drive(s), 7 heads, 29 sectors, 1624 cylinders 
Hard drive 1: present as 1 drive(s), 4 heads, 17 sectors, 305 cylinders 
Hard drive 2: not found. 


As mentioned previously, the number of cylinders reported for hard drive 0 is 
simply the maximum that can be reported by the interrupt used. In this case, the 
actual number of cylinders should be 1072, not 1024. The second hard drive 
reported (1) is actually a Bernoulli, rather than a conventional hard drive, but 
otherwise appears essentially correct. A third hard drive unit (2) was not found, 
nor present. 

One important factor to remember: This test can only identify physically 
separate units and cannot report the fact that hard drive 0 is actually configured as 
three logical drives labeled C:, D: and E. Nor can it recognize the fact that the 














Bernoulli is identified as F:. The test is, however, able to identify multiple physical 
drives joined as a single drive unit. 


Handling Interrupt Vectors 


Interrupt vectors are a means of redirecting a DOS or BIOS interrupt to a procedure 
within an application so that special handling can be applied. In theory, any DOS 
or BIOS interrupt can be vectored to an internal interrupt handler, though, in 
practice, this is only done in special circumstances. 

When it is done, however, the internal procedure must take over for the 
replaced interrupt—which means, in essence, accomplishing the same or a similar 
task in a compatible manner, and this can be both difficult, complex and slow 
without offering any real benefits. 

One interrupt, however, is frequently replaced by internal handling: the Ctrl- 
Break interrupt. 

Normally, when Ctrl-Break is entered, the program or application running is 
immediately terminated, with control returned to DOS. This can, however, mean 
that files are not updated and closed, that tasks are left undone and that things may 
be left in a general mess. 

It is possible, however, to redirect the Ctrl-Break handler to a local procedure, 
which can include shut-down provisions for any critical processes before terminat- 
ing. A simple version of a redirected Ctrl-Break handler is shown in Ctrl-Brk.PAS 
(end of this chapter) using the GetIntVec and SetIntVec procedures. 


GetintVec Procedure DOS 
The GetIntVec procedure returns the address stored in a specified interrupt vector. 
Declaration: GetIntVec( IntNo: byte; var Vector: pointer ); 


IntNo specifies the interrupt vector number (0..255), and the address of the 
interrupt is returned in Vector. 


See also: SetIntVec 
Example: See Ctrl-Brk.PAS at the end of this chapter. 


SetintVec Procedure DOS 


The SetIntVec procedure sets a specified interrupt vector to a particular address. 


Declaration: SetIntVec( IntNo: byte; Vector: pointer ); 
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IntNo specifies the interrupt vector number (0..255), and Vector specifies the 
address. Either the @ operator or the Addr function may be used to produce the 
address of an interrupt procedure. 


See also: GetIntVec 
Example: See Ctrl-Brk.PAS at the end of this chapter. 


Testing Ctrl-Brk.PAS 


The demo program Ctrl-Brk.PAS is slightly unusual, in that this program cannot 
be executed under the Turbo IDE because the IDE’s interrupt handler for the 1Bh 
(Ctrl-Break) interrupt takes precedence over the application, preventing the 
application’s interrupt handler from ever being triggered. 

The solution is simple. Compile the demo program to disk, then leave Turbo 
Pascal and execute the program from the command line. 


Summary 


This chapter covered a variety of special features ranging from interrupting pro- 
gram execution to running child processes and reporting run errors. Also, custom 
interrupt procedures were introduced, demonstrating how to use DOS and ROM 
BIOS interrupt features. Finally, it examined redirecting existing interrupt vectors 
to custom processes. 

The primary topic in Chapter 15, will be memory operations, facilities that 
allow storing and sorting records or other data without the use of data arrays. In 
Chapter 15, the directory list demo from Chapter 11 (Read_Dir.PAS) is revised to 
take advantage of pointer (memory) variables as well as the display techniques 
from Chapter 12. 


(SaSeeecek ee easeseesteSeseeeecsee@ estes kiessetascscseessses) 
{ Parent.PAS 
{ the Parent program will use the Exec procedure } 
{ to execute Child.EXE, a separate program which } 
{ must be compiled to disk before Parent can be } 
{ executed. Parent will also report the DOS exit } 
{ code number used by the child process } 
{SHSSSBSSSSSS Bets ssssSeseeeseserssseceses2z2eeee2ez2z22} 
{$M $4000,0,0 } { 16K stack, no heap required or reserved } 


uses Crt, Bes: 
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procedure ReportError; 
begin 
wreitet §DOS error: * 
case DosError of 


); 


2: writetn( ‘file net tound! =); 
3: writetna(..\peeni net found" -)> 
5: writeln( ‘access denied’ ); 
6: writeln( ‘invalid handle’ ); 
8: writetn( ‘insuttictent memory’ ); 
10: writeln( ‘invalid environment' ); 
11: writetn( ‘invalid format’ ); 
18: writeln(€ ‘no more files" ); 
else writeln(€ -‘#', DosError, ‘ unknown’. 77 
end; 
end; 
var 
1 ? tnteger; 
Dir pitecry 
Name NameStr; 
Ext Extstr; 
begin 
eLtreers: 
FSplitt Paranstr(0), bir, Name, Ext 2; 
for 1-32 7 te: 3 Go 
begin 
write( "Press ENTER to execute child ‘, 
'ePrecebhe: fo 4g Peg 
readln; 
SwapVectors; 
writeln( "Executing: >: Dire Chitd. EXE" 2; 
detay<t T9000 2; 
exec( Dirt'Child.EXE', chr€it$30) ); 
SwapVectors; 
writeln; 
if DosError <> 0 then ReportError else 
begin 
writeln( 'Child process @#', i, 
' reports back with the' ); 
writeln( ‘identifier ', lot DasExitCode ), 


' and the terminate code 
hi¢ DosExitCode 3: 23 
end; 
end; 
readln; 
end. 


' 
7 
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ee 
{ Child.PAS 

{ This program is called by Parent.PAS to 

{ demonstrate the EXEC procedure. 

{ Child.PAS must be compiled to disk 

{ before Parent can be executed 

{ Child identifies itself by its calling 
{ command Line parameter and returns this 

{ number as an exit code identifier. 
ee 


uses Crt: Bes; 


var 
1) 3° }-itecer: 

Ch -ehar: 
PStr 2 etPr ing: 


begin 
if ParamCount > O then PStr := ParamStr( 1°); 
Vet Petr i FS 
clrscr; 
Tor F277 Tt to. 20:6 
writeln(€ ‘This is child process ', ParamStr( 0 
' POOVCPECER aap Rete Ds 
writeln; 


write(€ 'Press any key to terminate: ' ); 

Ch := readkey; 

cl rscrs 

ROPER ds 

end. 

{seeseeeseseeeseeee2=e=es2e=)} 
{ RunError.PAS } 
{ demonstrates the } 
{ RunError procedure § } 
{sssssseseetese2eees22==} 


uses Dos; 


var 
k 20 nteger: Ch : cher: 


begin 
randomize; Kise nendemt 10° Jy 


WwHeYevuvve wv 


Chapter 14: Special Features and Custom Processes 261 


writeln(€ ‘A random exit integer has been chosen in the 
range 0..9" 3 

writeln(€ ‘ALL other characters will be echoed' ); 
repeat 

Ch := readkey; 

1% Ch <> enrt € #43350 2) then wrttet thie 

else 

case k of 


Os Runefrror¢ 30 7; 1: RUNErrort 37773 
2: RuNnErrort 525.2; 33 -RunErroert 33: 7; 
4: RunError¢ 58 2; Ss Rucerrert 53 2; 
6: Run€rrort 56-73 Te Runerrort 37 22 
S: Run&€rrort 56.2; Ge Runteror( 59 23 


end; 
until False; 
{ Remember: the error code reported by the IDE } 
{ was randomly chosen and, in this case, does- } 


{ not reflect an actual error } 
end. 
{sa=seeeeeeszessessesescez= } 
{ GetEquip.PAS } 
{ demonstrates using } 
{8A interrupt: cat. } 
{sesecanezvessreussteacnuss==)} 


uses Crt, POs; 


var 
Regs : registers; 
DPrint, DSerial, DFloppy, DVideo, i : word? 
DCopre :. string: 


procedure ReadEquipment; 
begin 
intré Sit, Regs. 23 
with Regs do 


begin .| see - 
DPrint = AX shr $OE; { OEhH-OFh } 
DSerial := (€ AX shr $09 ) and $07; { O9h-OBh } 
DFloppy s:= ¢ € AX shr $06 ) ‘and, S037 2% 1; { O06h-O7h } 
DVideo s= € AX shr $04 ) and $05; { O4h-O05h } 
+*° © AX. and. $02 ) = 0 { Oth } 


then DCopro := 'not found' 
else DCopro := ‘'present'; 

end; 

end; 
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procedure ReportFloppy( Drive byte J; 
begin 
with Regs do 
begin 
AH := $08; { function O8h 
DL := Drive; { drive number 
mer € $13, Reqs); { interrupt 13h 
if Flags and FCarry = O then { test carry flag 
begin 
wrttet. " Floppy drive ', chr $41+Drive ), 
Hane Be cehaala ie? Jee 
case BL of 
O12 WrPtelLAts*B60K). 40 Creech, SV 2577-32 
SOP: er itetnt 3 1 .24,: 8b track, Sieo 2 
SOS: write cnc U7TZ0K) BSE: track, 3.5%" 33 
S04: writetnt *4.5660R, 80 track, 3.5"": 33 
else writeln( ‘not present/identified' ); 
end; {case} 
end; 
end; 
end; 
function Report_HD( Drive: word ): boolean; 
var 
HDCnt, HDHead, HDSect, HDCyln word; 
begin 
with Regs do 
begin 
AH := $08; { function O8h 
DL := $80 + Drive; { hard drive inquiry 
intr Sits, Reas- )3 { interrupt 13h 
if Flags and FCarry = O then { test carry flag 
begin 
HDCnt = DL; 
HDHead := DH+1; 
HDSect := CL ana SSF; 
HEC¥IiAn t= 1 ee we oC Cl Shen OG) 2 84a: 2 
end else HDCnt := QO; { drive not found 
end; 
Wrtteci- Hand drive 72) Petveg. ore 93 


if HDCnt <> O then 
writeln( ‘present as ', 
HDHead, ' heads, ', 
HOCytn, '-éytinderse % 
else mritein(t 'not tound. *! 94 
Report: AP te HDCHt <> OC; 
end; 


HOCAt, © ' 


erivetse2.° "> 
nHoSect, 


1 SSCP ORS yo. ly 


} 
} 
} 
} 


wee Ye 
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begin 
ctrst¢tr,; 
ReadEquipment; 
writeln¢ ' Equinment. 0468 cunia * 29 
Wwriteink. * Pareliel portted: "=, DPriat. 2; 
writeln( ' Sertvat-porttad: ', OSertal 2; 
writeln(t * 80x67 coprocessor: ", DCopro ); 

| . 


write (¢€ ‘Initial video mode: ee 


case DVideo of 


0 : writeln( ‘undefined’ ); 7 OU. 2 
1 2 writetnt 7 60x25 Cotar’® 3; oe 5 ae. 
2: weitetnt “80e25 Color’ 2; t Os 
3 : writeln( "80x25 Mono' ); BNE ie Rae 
end; {case} 
writeln( ' Floppy. drive(s): >a: DElopay-oF 
for i 3:= 0 to OF loppy—1 do ReportFloppy( 1 77 
1-32 G2 
white Report NOC + 2: doectnes:. 3-35 
readln; 
end. 
{ssesersrssesseeses=e==} 
{ ExitProg.PAS } 
{ demonstrates the } 
{ Exit procedure } 
{ssestessstsrezeeezsesea=} 


usas Crt; 


var 
k : integer; 
Ch £ oner; 


procedure ExitProc; 
begin 

randomize; 

k := random( 10 ); 

writeln; 

writeln( 'A random exit integer has been chosen in the 
range O.«9"* #3 

writeln( ‘ALL other characters will be echoed' ); 


repeat 
Ch := readkey; 
if Ch = chrt k + $30 >) then exit 


elee. write C:Ch ); 
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end; 


beg 
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until False; 


A 


in 

Cirser: 

EXT tProc; 

writeln; 

wevtetnt the. exit key was ",5k.e3 
readln; 


end. 


use 


con 


var 


{$F 
pro 
beg 


end 
{$F 


beg 


{ Ctrl-C.PAS 
{ demonstrates the GetIntVec 
{ and SetIntVec procedure 


s Crt, bas: 


st 
BreakFlag : Boolean = FALSE; 


Int1BSave : Pointer; 


+ } 
cedure BreakHandler; interrupt; 
in 
GOtOSVE 3 272 el reat? 
writeln(€ ‘Break entered' ); 
sounds ,€40 2) devevt 108: }2 
sound( 4640 :7; ‘detay¢ 100.23 
nosound; delay( 1000 ); 
BreakFlag := TRUE; 
-} 
in 
GetIntVec( $1B, Int1BSave ); 
SetIntVec(€ $1B, Addr( BreakHandler ) ); 
WriteLn(€ "Press Ctrl-Break to exit' ); 
repeat 
WO PEBS a oe 
delay( 10 ); 
until BreakFlag; 
SetIntVec( $1B, Int1BSave ); 


end. 


Chapter 15 


Working with the System Memory 


In the examples in previous chapters, every time a variable was declared, memory 
space was allocated to hold the information that might eventually be stored in the 
variable. In the Parent.PAS program of Chapter 14, the {$M...} flag was used to 
ensure that the parent application left enough memory to run child processes. Thus, 
previously, memory management has been pretty much transparent—all handled 
by Turbo Pascal’s library routines and not requiring any consideration on the 
programmer's part. 

The drawbacks of static memory allocation—using fixed variable declarations 
or arrays of variables—are principally the restrictive aspects. For data arrays, the 
static declaration must be large enough to contain all possible data in all possible 
circumstances. However, this is, in itself, limiting because this statically allocated 
memory can only be used for one purpose, the named variable or array, and, no 
matter how small the requirements of the actual data, the size of the memory block 
is fixed at the time the program is compiled. 

The advantages, for small amounts of data or small arrays, are that the data can 
be referenced by name or index, assignment operations are simple and flexible, and 
there is relatively little possibility for error. 

But there are also alternatives. Dynamic memory allocation provides flexible 
memory storage. Memory for data can be allocated on an as needed basis rather 
than being allocated in advance. Also, data storage is limited only by the amount 
of memory available, not by the size of a predetermined array. Equally important, 
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memory can also be deallocated—freed for other uses when the original allocation 
is no longer required. 

In Chapter 16, the program Pop_Dir demonstrates how data can be stored in 
dynamic memory, using pointers rather than data arrays. Dynamic allocation has 
other advantages aside from the freedom of size, because information in dynamic 
memory can be manipulated by sort processes, for example, faster than statically 
allocated memory. 

Relational links are another advantage of dynamic memory allocation, provid- 
ing flexibility and freedom in cross-referencing, as well as speed in tracing relational 
links. 

If your application is given a free hand to manage memory dynamically, 
however, you also need to be able to free memory for reuse. If memory is not freed, 
it is available for the current application but may not be available to other applica- 
tions after the allocating application exits. So, this isn’t a free lunch—along with 
increased freedom come requirements for responsible memory management as 
well. 

Before going into the details and examples of using dynamic memory, we will 
introduce a few tools for memory management. 


DOS Memory Organization 


Figure 15-1 shows how DOS memory is organized from the viewpoint of a program 
that is being executed. 

The program begins with a PrefixSeg in low memory—a 256-byte area created 
by DOS when the .EXE program is loaded. The segment address is available in the 
predefined word variable PrefixSeg. 

This location is not, however, the bottom of the DOS memory. Below this point, 
and not shown, the lowest memory is occupied by DOS itself, together with any 
resident TSRs, device drivers, and so on. Therefore, when we refer to low memory, 
the reference means the lowest memory available to the application. 

Above the PSP, the main program code segment is loaded, and, above this, the 
unit code segments. These consist of code belonging to units listed in the uses 
statement. They are loaded in the order listed, with the system unit (TURBO.TPL) 
code at the top. 

Above the units, all typed constants are loaded, beginning at the data segment 
address (DSeg:0000). Above the constants, memory space is allocated for all global 
variables. 
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After space is allocated for the constants and global variables, the SSeg:0000 
address identifies the bottom of the reserved stack space, and the stack pointer is 
initialized, by default, 16K bytes higher. Stack space allocation may be changed 
with the {$M...} directive, but cannot exceed 64K. 

In use, the stack grows down from the stack origin until the SSeg:0000 point is 
reached, and the stack is exhausted. 

If any program overlays are used (see Chapter 17), the overlay buffer is 
allocated above the stack space. The default size of the overlay buffer is the size of 
the largest overlay used, but it can be changed through the OvrSetBuf routine in 
the Overlay unit. When no overlays are used, the overlay buffer is not allocated. 

Above the overlay buffer, if there is one, the HeapOrg pointer marks the 
beginning of the heap space. Above this point, the HeapPtr tracks the top of the 
heap up to the top of free memory. The default minimum heap size is 0K, and the 
default maximum is 640K, meaning that the heap will occupy all remaining 
available memory, unless, as in the Parent.PAS program earlier, the heap size has 
been explicitly reduced. 

\ In addition to providing the conventional memory management utilities, the 
functions and procedures described in this chapter also provide access to 
(addresses or pointers to) several of these memory pointers. 


Memory Usage 


Turbo Pascal provides two functions that report on memory usage—or, more 
accurately, report memory availability. 


MaxAvail Function TURBO.TPL 


The MaxAvail function reports the size of the largest contiguous block of free 
memory in the heap. 


Declaration: MaxAvail: longint; 


The MaxAvail function returns a longint value reporting the largest single 
memory block available. This corresponds to the size of the largest single dynamic 
variable that can be allocated at that time. In Figure 15-2, MaxAvail would report 
the size of the memory block between the HeapPtr and the HeapEnd, but would 
not include the two smaller blocks of free memory between Ptr1 and Ptr4 and 
between Ptr4 and Ptr6. 
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Additional memory may be available but fragmented in smaller blocks, while 
the MemAvail function will report the total of all available memory on the heap. 


See also: MemAvail 

Example: 

begin 
writeln( ‘Largest memory block available: ', MaxAvail ) 
wryvteintk “ Total memory available: ', MemAvail ) 
readln; 

end. 


Ss Ne 


Note: Unless memory allocation and deallocation functions have been called 
(as shown in Figure 15-2), the heap should be unfragmented, and both MaxAvail 
and MemAvail should report the same value. 


MemAvail Function TURBO.TPL 


The MemAvail function returns the sum of all free memory blocks in the heap. 
Declaration: MemAvail: longint 


The MemAvail function adds the sizes of all free memory blocks, reporting the 
total amount of free memory in the system. In Figure 15-2, MemAvail would show 
the total of all of the areas of free memory. 


See also: MaxAvail 
Example: See MaxAvail example, above. 


$M Compiler Directive © TURBO.TPL 


The {$M directive specifies memory allocation parameters for an application. 


Declaration: {$M stacksize, heapmin, heapmax} 
Default: {$M 16384, 0, 655360} 


The memory allocation size directive specifies the memory allocation parame- 
ters to be used by an application. Stacksize is an integer parameter in the range 
1,024..65,520 (1K..64K) and sets the size of the stack segment. Heapmin must be in 
the range 0..655,360 (0..640K), and Heapmax must be in the range heapmin..655,360 
(??..640K). 

The heapmin parameter establishes the minimum memory size that must be 
available for the heap after a program loads (or else the program cannot operate). 
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The heapmax parameter sets the maximum heap size that the program will 
reserve for its own use. 

In the Parent.PAS program in Chapter 14, the instruction {$M $4000, 0, 0} 
established a 16K stack but reserved no memory for the heap. 


Figure 15-2; Memory Management 
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Allocating Memory 


Turbo Pascal provides two procedures to allocate memory for dynamic variables, 
the GetMem and New procedures. 

With either GetMem or New, if insufficient free memory exists on the heap (as 
a single contiguous block) to allocate the new variable, a run-time error is reported. 
Testing by calling MaxAvail can prevent errors, or a heap error function can be 
created (see Chapter 16 in the Turbo Pascal Programmer's Guide). 


GetMem Procedure TURBO.TPL 


The GetMem procedure creates a new dynamic variable of a specified size, return- 
ing the memory address in a pointer variable. 


Declaration: GetMem( var P: pointer; Size: word ); 
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Pisa pointer variable of any pointer type and Size is an expression of type word 
specifying the variable size in bytes. The new variable can be referenced as P”. 

One limit applies: The largest single block that can be allocated is FFF1h bytes 
(65,521 bytes), but if the heap is not fragmented, successive calls to GetMem return 
successive blocks of memory. In this fashion, larger contiguous blocks of memory 
can be allocated, but the addresses returned should be tested to ensure that they 
are actually contiguous. 

FreeMem is used to release memory allocated by GetMem. 


See also: Dispose, FreeMem, Mark, New, Release 
Example: See ShowMem.PAS at the end of this chapter. 


New Procedure TURBO.TPL 


The New procedure creates a new dynamic variable, returning the memory address 
in a pointer variable. 


Declaration: New ( var P: pointer [, Init: constructor | ); 


P is a pointer variable of any pointer type. The size of the allocated memory 
block corresponds to the size of the type P points to, and the new variable is 
referenced as P%. 

The New procedure has been extended to permit a constructor call as a second 
parameter and is used in allocating dynamic object variable types. In this case, P is 
an object pointer and Init is the constructor method for the object type. This second 
usage is explored further in a later section on object-oriented programming. 

Dispose is used to release memory allocated by New. 


See also: Dispose, FreeMem, GetMem, Release 
Example: See ShowMem.PAS at the end of this chapter. 


Managing Memory Usage 


Two different memory management systems are provided by Turbo Pascal, repre- 
sented by the Mark and Release procedures and the Dispose and FreeMem proce- 
dures. As arule, the Mark and Release memory management cannot be mixed with 
the Dispose and FreeMem processes, and applications should use one or the other 
but not both. Of course, there are exceptions, but we will follow this rule at present. 

The Mark and Release memory management system is the simpler of the two. 
It uses the Mark procedure to record the initial state of the heap (the heap pointer), 
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while the Release procedure deallocates everything assigned by the New or Get- 
Mem procedures since Mark was called. 

The Dispose procedure is used to deallocate dynamic variables individually. 
The FreeMem procedure is similar but releases a block of memory of a specified 
size. For general use, New and Dispose are recommended over GetMem and 
FreeMem. 


Mark Procedure TURBO.TPL 
The Mark procedure records the heap state (heap pointer) as a pointer variable. 
Declaration: Mark( var P: pointer ); 


P is a pointer variable of any pointer type. The current value (address) of the 
heap pointer (as shown in Figure 15-2) is returned in P for later use as an argument 
to Release. 


See also: Dispose, FreeMem, GetMem, New, Release 
Example: See ShowMem.PAS at the end of this chapter. 


Release Procedure TURBO.TPL 
The Release procedure returns the heap to a given state. 
Declaration: Release( var P : pointer ); 


Pis a pointer of any pointer type, which was previously assigned with the Mark 
procedure. Release deallocates any dynamic memory variables that have been 
allocated by New or GetMem since P was assigned. 

If Release were called with Ptr1, as shown in Figure 15-2, the HeapPtr would 
be restored to Ptr1, releasing everything above this point in the heap. 

Calling Release(Ptr6) would release only the area between HeapPtr and Ptr6, 
except that there is an area below Ptr6 that was deallocated by some other means 
but, after this call, is suddenly considered to be in use again. This is one reason why 
the two different memory management approaches do not mix well. 


See also: Dispose, FreeMem, GetMem, Mark, New 
Example: See ShowMem.PAS at the end of this chapter. 


Dispose Procedure TURBO.TPL 


The Dispose procedure deallocates memory used by a dynamic variable. 
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Declaration: Dispose( var P: pointer [, Destruct: destructor | ); 


P is a pointer of any type previously assigned by the New procedure or by an 
assignment statement. Dispose destroys the variable referenced by P, releasing the 
memory allocated to the heap. After a call to Dispose, the value of P is undefined, 
and it is an error to subsequently reference P%. 

In Figure 15-2, the Dispose procedure might have been used to release blocks 
of memory in the areas below the HeapPtr, which are now shown as free memory. 

Like the New procedure, Dispose has been extended to allow a destructor call 
as a second parameter for disposing of a dynamic object variable type. In this case, 
P is a pointer to an object type, and Destruct is the destructor method of the object 
type. This second usage is explored further in a later section on object-oriented 
programming. 

If P is not a valid memory pointer, a run-time error occurs. 


See also: FreeMem, GetMem, Mark, New, Release 
Example: See ShowMem.PAS at the end of this chapter. 


FreeMem Procedure TURBO.TPL 


The FreeMem procedure disposes of a dynamic variable of a specified size. 
Declaration: FreeMem( var P: pointer; Size: word ); 


P is a pointer variable of any type, which was previously assigned by the 
GetMem procedure or by an assignment statement. Size is an expression of type 
word specifying the exact number of bytes of memory to be disposed. It must be 
exactly the same size as previously allocated by GetMem. 

FreeMem destroys the variable reference by P, releasing the memory allocated 
to the heap. After a call to FreeMem, the value of P is undefined, and it is an error 
to subsequently reference P%. 


See also: Dispose, GetMem, Mark, New, Release 
Example: See ShowMem.PAS at the end of this chapter. 


Freed Memory Considerations 


When either the Dispose and FreeMem functions are called to free memory pre- 
viously allocated, the first eight bytes of the freed memory—which previously 
contained a pointer to the next free block and the size of the current block—are 
overwritten. While the remainder of the allocated memory block is not rewritten 
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until used by another process and, therefore, may still contain information, it is not 
reliable programming practice to subsequently reference this memory address. 


Memory Address Operators 


Along with allocating and deallocating memory, Turbo Pascal supplies memory 
address operators in the form of the Addr, Ofs, Ptr and Seg functions and the @ 
operator. These allow applications to reference memory addresses directly, as 
opposed to indirect references via variable names and procedure and function 
names. 


Addr Function TURBO.TPL 


The Addr function returns a pointer with the memory address of the specified 
object. 


Declaration: Addr( X ): pointer; 


X is any variable or procedure or function identifier. Addr returns a pointer 
with the address of X, which is assignment compatible with all pointer types. Note: 
the @ operator produces the same result. 


See also: Ofs, Ptr, Seg 


Example: 
var 
Ps potniter: 
begin 
Pst (AGERE PH) 
P s= @aP-s 
end. 


Either instruction makes P point to itself. 


Ofs Function TURBO.TPL 
The Ofs function returns the offset of an object. 
Declaration: Ofs( X ): word 


X is any variable or procedure or function identifier. Ofs returns a word value 
with the offset portion of the address of X. 


See also: Addr, Seg 
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Example: 
var 
WwW: word: 
begin 
W := OfsC W ); { W holds its own offset address } 
end. 


Seg Function TURBO.TPL 
The Seg function returns the segment address of an object. 
Declaration: Seg( X ): word; 


X is any variable or procedure or function identifier. Seg returns a word value 
with the segment portion of the address of X. 


See also: Addr, Ofs 


Example: 
var 
Ww. £ werd; 
begin 
W := Seg W ); { W holds its own segment address } 
end. 


Ptr Function TURBO.TPL 
The Ptr function converts a segment and offset address to a pointer value. 
Declaration: Ptr(S, O: word ); 


S and O are expressions of type word. The result is a pointer to the address 
given by the segment and offset values. The result returned by Ptr is assignment 
compatible with all pointer types. 


See also: Addr, Ofs, Seg 


Example: 
var 
S$, GO + word: 
P “Sy¥tes 
begin 
GC ¢= OF 68 F--23 
S$ s= Segt P J}; 
P se Pert §, O- de CoF: potnts to itself } 
P s= Ptrt $40, $49 Dd; 
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writetat:c Video: mode ‘tes * 5 :F* 222 
{ P points to the value of the video mode } 
end. 


Direct Memory Operations 


Along with provisions for memory addresses, one procedure, Move, and three 
predefined arrays, Mem, MemW and MemL, can be used for direct memory access. 


Move Procedure TURBO.TPL 


The Move procedure copies a specific number of contiguous bytes from a source 
address to a destination address. 


Declaration: Move( var Source, Dest; Count: word ); 


The Source and Dest arguments are variable references of any type—.e., 
variable names of any type or pointer addresses. Move copies Count bytes from 
the first byte of the Source address to the first byte referenced by the Dest address. 

No checking of any kind is performed, and Count may extend beyond the size 
of the Source reference or the Dest location. Also, no type checking of any kind is 
applied. Therefore, Source and Dest may reference completely incompatible data 
types without conflicting with this operation. 

Extreme caution is suggested when you use Move. Whenever possible, it would 
be well to use the SizeOf function to determine Count. 


See also: FillChar 


Example: 
var 
A Srreyvicing 122.0: ener 
By C228) 8S tongint. 
begin 
Movet As By sizeof A.) 2; 
end. 


Remember, with Move, no range checking is applied. Therefore, since a longint 
value is four bytes, and the array A occupies 12 bytes, the result of the Move 
operation is that A is copied to B and C and D, because these three static longint 
variables would have been allocated contiguous memory locations. 

If, however, C and D had not been so providently declared in a fashion to 
provide this contiguous memory block, two thirds of A would have been copied to 
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the memory location following B but used by some undetermined memory variable 
(or, perhaps, not used at all). 


Mem, MemW,MemL~ Arrays  TURBO.TPL 


The Mem, MemW and MemL arrays are predefined and provide convenient direct 
access to memory. Elements of Mem are byte-sized, MemW, word-sized and MemL 
are longint (4 bytes). 

The Mem arrays are not like static variable arrays but can be used to reference 
any part of memory by supplying an appropriate index value in the form of a 
segment:offset memory address. All three arrays expect two expressions of integer 
type word, separated by a colon, and may be used to reference or set values 
anywhere in memory without typecasting or other restrictions. 


Examples: 
Mem£C $0040 : $0049 J := Video_Mode; 


This example sets the byte value at 40h:49h to the Video_Mode value. Of course, 
there is no guarantee that the value set is a valid video mode, but the address used 
is correct for the intended operation. 


DataWord := MemWCL seg X ) : ofs(€ X ) J; 
In this example, DataWord receives a word value, copied from the address of X. 
LongData := MemLC seg( M ) : ofs€ M ) + N¥4 J; 


In this last example, assuming M is an array of longint, and N is an index value, 
then LongData takes the longint value of M[N]. 


Internal Register Addresses 


Turbo Pascal also provides functions returning several internal register values. 
These are not generally needed by the programmer, but are available if and when 
required. 


CSeg Function TURBO.TPL 


The CSeg function returns the current value of the CS register as a word value. The 
result is the segment address of the code segment where CSeg was called. 

Referring to Figure 15-1, the address returned by CSeg would be somewhere 
in the main program code segment or in the overlay buffer area. 
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Declaration: CSeg : word; 
See also: DSeg, SSeg 


DSeg Function TURBO.TPL 


The DSeg function returns the current value of the DS register as a word value. The 
result is the segment address of the data segment. Figure 15-1 shows the DSeg 
pointer at the bottom of the space allocated for typed constants. 


Declaration: DSeg : word; 
See also: CSeg, SSeg 


SSeg Function TURBO.TPL 


The SSeg function returns the current value of the SS register. The result is a word 
value with the segment address of the stack segment. The SS register—see Figure 
15-1—is the pointer at the top of the stack space. 


Declaration: SSeg : word; 
See also: SPtr 


SPtr Function TURBO.TPL 


The SPtr function returns the current value in the SP register. The result is a word 
value with the offset value of the stack pointer within the stack segment. SPtr is 
shown in Figure 15-1. The absolute address of the stack pointer would be referenced 
as SSeg:SPtr. 


Declaration: SPtr : word; 
See also: SSeg 


Summary 


In this chapter, the DOS memory structure and memory management processes 
have been discussed. The demo program, ShowMem.PAS, listed below, demon- 
strates the principal memory management routines. These will appear further in 
later examples. 

Except for the overlay procedures, which are discussed briefly in Chapter 17, 
this completes coverage of most of the basic tools provided in Turbo Pascal. Chapter 
16 puts it all together, using these tools to create a complete application, and, in the 
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process, introducing a number of programming techniques, as well as a few 
programmer’s tricks. 

The latter category, programmer’s tricks, are shortcuts that are perfectly valid 
programming practices but involve bits of extra knowledge that can’t really be 
taught but are acquired through experience. 

While they can’t be taught in the sense of a programming course, a few 
examples show that alternatives do exist and, frequently, may be faster or more 
efficient for some tasks than conventional processes. 


uses Crt; 


const 


KByte 


type 


BPtr 


{ssSesSsertessesesee2esSssrcseqcsass= 
{ ShowMem. PAS 

{ demonstrates memory 

{ management procedures 
{ssSex32eSrsrecseersesrSesssscercs=s 


1024; 


ABigBlock; 


BigBlock = arrayf€1..KBytel of lLongint; 


var 


GPtr 


GM 
SM 
BK 


i, 


j 


pointer; 

arrayli..3] of potnter? 
arrayl1..341 of words 
arvayit«iS2 of BPtr: 
integer; 


procedure ReportMemory,; 


begin 


writeln(¢ 


writeln(¢ 


end; 


' Total available memory is: 
; ( ', MemAvail div KByte, 
, Maximum block size is: 
: ( ', MaxAvail div KByte, 


procedure MemCheck; 


begin 


gotoxy( 40, WhereyY ); 
writeln¢ ' Tot: ', MemAvail div KByte, 
: Max: ', MaxAvail div KByte, 


end; 


| 


nA. 


MemAvail, 
Ree ae 
MaxAvail, 
2o ie 3 


2 eae 
'K! 3 


Zry 
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begin 
randomize; 
{ssesecosSrecsresee='= =} 
{ Mark / Release } 
{seseeeeseeeecees=z=} 


clrecr? 
ReportMemory; 
writeln; 
writeln(€ ‘Demonstrating the Mark / Release routines' ); 
writeln; 
Mark(€ GPtr ); 
FOC EST £07.35 do 
begin 
1 Fe pandomt 100° 7° 4° 13 
weitet *Aitocatinge « ', i, “hey te: memory Block ...' 2: 
GetMem( GMCLiJ, j*Kbyte ); 
MemCheck; delay( 2000 ); 
end; 
writeln; 
writeln(€ 'Deallocating all memory ( Mark / Release ) ' ); 
writeln; 
Release( GPtr ); 
ReportMemory; 
writeln; 
wri tel: 'Pree@s ENTER ' Dd: 


readln; 
{ssessse2esses2ee22e222=2) 
{ GetMem / FreeMem_ } 
{ssessseeesesee2es22==) 
clrscr; 


ReportMemory; 
writeln; 
writeln(€ ‘Demonstrating the GetMem / FreeMem routines' ); 
writeln; 
TOP 7 t84 to 3 Go 
begin 
SMCiJ := (€ random( 100 ) + 1) * KByte; 
writeC "AlttToceting « *,; SHEITI div: Kbyte; 
' KBYte Memery Biock 2.4.7 >) 3 
GetMem(€ GMCiJ, SMCiJ] ); 
MemCheck; delay(¢ 2000 ); 
writeln; 


end; 

for i 

begin 
write (¢ 
FreeMem( GMLid, 
MemCheck; 
writeln; 

end; 

writeln; 

ReportMemory; 

writeln; 


1 to 38. €6 


write( 'Press ENTER 
readln; 
{ 
{ 
{ 
eireer: 


ReportMemory; 
writeln; 
writeln¢ 
writeln; 


TOr 4.3: 1 to 3. eo 
begin 
write(€ ‘Allocating a 


' KByte memory block ....* 


New( BKCid ); 


'"Deallocating ', 
SMC id: 
delayt 2000: 2s 


Chapter 15: Working with the System Memory 281 


i] ) 2 


‘Demonstrating the New / Dispose 


‘, Sizgeot( BEETI¢ 
; 


sizeott. BKLiJ* 


3 


MemCheck; delay( 2000 ); 
writeln; 

end; 

Tor 4 t= Tt té. 3 do 

begin 
write€ 'Deallocating ‘', 

'* Keytes ° 23 

Dispose( BKCid ); 
MemCheck; delay( 2000 
writeln; 

end; 


writeln; 
ReportMemory; 
writeln; 
write( 'Press 
readln; 

end. 


ENTER 


L] ae 


SMCTiJ div KByte," 


Koytes ° Dz 


routines’ J); 


) div KByte, 


) div KByte, 


on ~ ao mai ‘ = 
wi AMs % fy 


Stim 
, 
; 


« 
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Chapter 16 


Putting It All Together 


Thus far, we have concentrated on the facilities offered by Turbo Pascal: the 
procedures, functions and other elements that comprise the tools for creating 
application programs. In building applications, a comprehensive tool kit is impor- 
tant, but how you put the tools together to create an application is equally impor- 
tant, or even more so, 

In this chapter, we will use the tools explained in previous chapters to build a 
complex application that supports a variety of features. 

This demonstration program will introduce a few programmers’ tricks of the 
trade—shortcuts that provide features not explicitly supported by Turbo Pascal 
routines but still valid implementations. It will also implement at least one custom 
function using interrupt calls. 

The first new feature to be introduced is the practice of using ‘include’ files. 


Using Include Files in Source Code 


Include files allow long or complex program source code to be broken into multiple, 
smaller files. You might want to do this for several reasons: 

First, if your source code size has exceeded the memory available to the Turbo 
Editor, breaking the code into multiple include files relieves the conflict. 

Second, if the size of your source code has become inconveniently large for you 
to work with, creating several smaller include files permits editing and revision 
without having to wade through irrelevant code. 
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Third, include files might contain finished program code comprising a com- 
plete utility or feature that can be used by more than one program. 

The PopDemo.PAS and PopDir.INC programs (full listings at the end of this 
chapter) demonstrate the second and third reasons for using include files. The first 
reason, exceeding the editor’s capacity, is not as easily managed. 

PopDemo.PAS is relatively brief and simply serves as a shell for creating a 
background screen before calling and demonstrating the Pop_Directory function. 

However, the Pop_Directory function is found in an include file, which is 
referenced as: 


uses Crt,..Bos8? 


{$I POP_OIR. INC} 


The {$I directive appeared earlier in the forms {$I-} and {$1+} to turn input/out- 
put error checking off and on. In this example, however, the {$I filename} directive 
instructs the compiler to include the named file during compilation of the present 
file. 

The {$I include directive assumes a default extension of .PAS, but any other file 
extension may be used by explicit statement. Also by default, if no directory is 
specified, Turbo Pascal searches first in the current (active) directory and then 
searches in the directory or directories specified in the IDE’s Options / Directories 
/ Include directories input box. Directory selection for both the current directory 
and the include directories was detailed in Chapter 2. 

Two restrictions apply to include files: First, include files cannot be nested 
deeper than 15 levels. An include file called by a program source code file is the 
first level, but the include file can, itself, call one or more other include files (second 
level) and these, in turn, can call further include files (third level), and so on. 
Granted, this is not a very realistic prohibition, but it does exist. Anything over five 
or six levels of include files probably means that this feature is being overworked, 
and you need to rethink your program organization. Unit Compilation, introduced 
in Chapter 17, is one alternative. 

Nesting is used in the PopDemo program, the Pop_Dir.INC source file calls two 
other include files: 


{$I FRAME. INC:  } { draws box frames for display ... } 
{$I POP UPLING 7} { provides save screen procedure, etc } 
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Thus, when PopDemo is compiled, these are second level include files, but this 
is the limit of the include nesting used here. 

The second restriction on include files is this: Include files cannot be called from 
within a begin..end block because all statements within a block must reside in the 
same source file. Include statements may appear at the beginning of a file—making 
the included routines available globally—or they can appear between the proce- 
dure or function declaration and the beginning of the subroutine, which makes the 
routines within the include file local to the subroutine. 


The Include Files 


The Include files used in this chapter show, first, how related program elements 
can be grouped and removed from the main program to reduce the size of the source 
code. The Frame.INC and Pop_Up.INC include files are examples of this approach. 

The Frame.INC file contains three box/line drawing procedures, which are 
used to create a display frame. 

The Pop_Up.INC file is a bit more complicated. It includes several global 
variable definitions, as well as a half-dozen routines for saving and restoring screen 
images, setting colors, writing captions, and checking keyboard character and 
special character events. 

The Pop_Dir.INC file is the real utility. It provides a single function named 
Pop_Directory, which is called with a screen offset position and a file specification 
and returns a directory /path/filename to the calling application. Since Pop_Dir is 
created as an include file, this utility can be used by more than one application 
without being recreated for each application. (Complete listings for all four files 
appear at the end of this chapter.) 

The Pop_Directory function uses external routines from the Frame.INC and 
Pop_Up.INC include files and has full access to the global declarations made in 
Pop_Up.INC. However, Pop_Directory also declares its own local subroutines and 
its own local constants, types and variables, which are not accessible except by the 
Pop_Directory function. Scope for each program block is shown by shading in 
Figure 16-1. 

In the Pop_Demo program, the first statement following the comment header 
is the include statement for the Pop_Dir file, while the local variable declarations 
follow the include statement. This ordering ensures that the scope of the local 
variables declared does not encompass the include file. 
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Figure 16-1: Scope and Include Files 


Pop_Demo.PAS 
Pop_Dir. INC 


Frame . INC 


Pop_Up. INC 





In like fashion, the Pop_Dir.INC file begins with two include file declarations, 
Frame.INC and Pop_Up.Inc. The second of these, Pop_Up.INC, begins with several 
variable declarations that are global to the include file and, therefore, global to 
Pop_Dir.INC and even to Pop_Demo.PAS 


The Save Screen and Restore Screen Procedures 
Pop_Up.INC includes features to save and restore text screen images, allowing the 
Pop_Directory function to overwrite an existing text screen and, after its task is 
finished, restore the original screen before exiting. 

In order to save a screen image, we must first declare a special data type: 
type 

Screen Sarreylt..25,1..60) of: word; 

The Screen type is defined for a 25-line screen, 80 columns wide, which is 
enough even if a 43- or 50-line screen mode was active, since Pop_Directory will 
not attempt to write beyond the 25th line in any case. Thus, Screen proves an array 
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holding one word value for each screen position—exactly enough to hold both the 
screen attribute byte and the character byte for each position. 

This array could have been declared simply as: array[1..4000] of byte or in any 
other equivalent form, but a double indexed array of word matches the screen 
row/column arrangement and can be useful in other ways. 

Note: It is much easier—and faster—to save the entire screen than to save and 
restore only a selected portion of the screen. 

Next, since we need to support either a color or a monochrome system, 
Pop_Up.INC begins by declaring two variables: 


var 
MonoScreen : Screen absolute $B000:$0000; 
ColorScreen : Screen absolute $B800:$0000; 


These two arrays are declared at absolute addresses corresponding to the 
monochrome and color video addresses. In other words, instead of allocating space 
on the system heap, these arrays overlie the existing video memory addresses used, 
respectively, by monochrome or color video cards. 

The fact that the system running the application has only one of these video 
cards is immaterial. Further, if no memory at all exists at the alternate address, this 
is equally irrelevant because only one address will actually be used—the address 
of the installed video card. Even if additional memory is installed at the alternate 
address, this also has no effect for the same reason—it will not be referenced. 

Declaring both addresses makes future operations convenient simply because 
the two declarations are then available as ‘handles’ to reference either the mono- 
chrome or color video memory. 

However, a more conventional variable declaration is also needed to provide a 
place to store information read from the screen: 


KeepScreen : arrayl1..2] of Screen; 


The array KeepScreen provides space to store two copies of the text screen. 
These are allocated, quite conventionally, on the system stack, but if memory usage 
is a consideration, they can be created dynamically using the New procedure 
introduced in Chapter 15, and when no longer needed, deallocated using the 
Dispose procedure. 

For the present, the simpler process of declaring two static arrays will suffice. 
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Because of the “trick of the trade” used in declaring MonoScreen and Color- 
Screen as arrays at absolute addresses, the Save_Screen and Restore_Screen proce- 
dures are simplicity itself. 


procedure Save_Screen( ScrNum: byte ); 
begin 
ColorVideo := (€ LastMode Mono ); 
if ColorVideo then 
KeepScreenl ScrNum J 
KeepScreenl ScrNum J 


ColorScreen else 
MonoScreen; 


end; 


The Save_Screen procedure begins by checking the current text mode setting 
to decide if the system is monochrome or color, storing the result in the global 
boolean variable ColorVideo. Depending on the test result, the array KeepScreen 
is assigned to one of the two video arrays. 

Very simply, this assignment results in the contents of the second array being 
copied, as a block, to the first array. Without the address assignment using the 
absolute address, this information would probably have to be copied using a pair 
of loops such as: 


Tor 423 4. te-25 do 
TOF: Fe seo te B0' do 
KeepScreenli,jJ := MemWC $B800, ((i-1)*80+j)*2 1; 


The shortcut, however, is not only simpler but also tremendously faster. 

Also, the Save_Screen procedure is called with a byte value to select an element 
of the KeepScreen array. To restore the text screen, the same index is used in calling 
Restore Screen, thus: 


procedure Restore_Screen( ScrNum: byte ); 
begin 
if ColorVideo then 
ColorScreen := KeepScreenl ScrNum J] else 
MonoScreen := KeepScreenL ScrNum J]; 
end; 


This copies the stored information back to the screen memory just as quickly— 
and just as accurately—as the original operation. 


Reading the Screen—A Shortcut 


It has been suggested that the declarations of the ColorScreen and MonoScreen 
arrays have other applications aside from copying the screen contents, and that 
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there were reasons for using a double-indexed array in the definition of the type 
Screen. While not used in the present application, one alternative use of this 
approach is a convenient procedure for reading characters back from the screen. 
The Read_Screen procedure is easily implemented but does, initially, require 
two additions to the Pop_Up.INC definitions. 
First, a new type declaration is required: 


ScrPtr = *Seresn;: 
Second, a new variable is declared as screen pointer: 
ActiveScreen : ScerPtr, 


With these two additions (which are already incorporated in the complete 
listings and the disk files), the demo program ReadScr1.PAS (the final listing in this 
chapter) begins with an include statement for Pop_Up.INC. 

The demo program provides two subroutines, beginning with the procedure 
Check Mode, which parallels another test in Pop_Up.INC: 


procedure Check_Mode; 
begin 
if LastMode = Mono 
then ActiveScree 


n := @MonoScreen 
else ActiveScreen := @a 


ColorScreen; 
end; 


In the previous Save_Screen and Restore_Screen procedures, a global boolean 
variable, ColorVideo had been set using the same test executed here. But in both of 
these routines, the operation executed was assigning one array to another (ie., 
copying the contents of one array address to another). 

Here, however, the operation is slightly different. An address is being assigned 
to a pointer variable, ActiveScreen. After this has been done, ActiveScreen is a 
pointer to the active video memory. 

Because this is a pointer operation, another option is opened. When Active- 
Screen is created (declared as a variable), the pointer has an initial value of nil—a 
value that can be tested. The Read_Screen procedure begins by doing exactly this 
whenever it is called. 


function Read_Screen( XPos, YPos : byte ): char; 
begin 

Read_Screen := chr( Lo ActiveScreen“*C YPos, XPos J] ) ); 
end; . 
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Read_Screen returns the character value of the low byte of the word value at 
the array location corresponding to a specific row/column position. But there are 
two differences here from conventional array assignments: 

First, ActiveScreen is a pointer to the array address, not the array itself. 
Therefore the syntax for referencing an array element is slightly different. It requires 
the pointer operator (“ or carat) to reference the actual array assigned to the pointer 
address. 

The second difference is simpler but equally important. You should, by this 
time, be accustomed to referring first to the column value and second to the row 
value, as in the GotoXY procedure, the Window procedure and others. The array 
Screen, however, references the row value first and the column value second 
because this is how the actual memory assignments are organized. 

The definition of Screen could be expanded as: 


arreylt..801 of word: 
errayveii. 251: 6% Serkows 


ScrRow 
Screen 


This might make the organization a bit clearer, but wouldn’t actually create 
anything different, since Screen still has to match the physical video memory map. 

Furthermore, as far as the computer is concerned, all of this memory is simply 
a linear array. The double-index is used for our convenience. Therefore, instead of 
saying: Screen[ YPos, XPos ], it’s equally valid to say Screen[ ( YPos — 1 ) * 80 + XPos | 
or to say Screen[ XPos + ( YPos — 1 ) * 80 ]. But, in the final analysis, these last two 
versions are exactly what the compiler does anyway; converting the double index 
into a single offset address. 

However, this is another example of why, even though you’ re using a high-level 
language, you still need to understand what’s actually happening behind the scenes 
and how the computer is actually handling your requests. As we pointed out before: 
What you don’t know may not hurt you, but it definitely can’t help you. 

Aside from these two subroutines, ReadScr1.PAS, is quite straightforward. 


Reporting Key Strokes 


The Pop_Up.INC file also includes two global character declarations, Ch and KCh, 
and the CheckKbd procedure, which follows the same general format discussed 
earlier of testing keyboard activity. In this version, however, ordinary ASCII values 
are returned in Ch, or, if a function or cursor key was pressed, Ch is given a null 
value (00h) and KCh receives the char value identifying the key pressed. 
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The Smart Linker and Include Files 


While the include file Pop_Up.INC is used by two different demo programs, it also 
has type definitions, variables and procedures that are not used in both cases. This 
does not mean, however, that excess material will be added to the .EXE program 
compiled because, as mentioned previously, the Turbo Pascal smart linker only 
incorporates routines from units or include files that are actually used by the 
application. 

When the ReadScr1 program is compiled, for example, the Save_Screen, 
Restore Screen, Set_Color, etc. procedures that are defined in the Pop_Up.INC 
include file are not incorporated in the compiled .EXE program because these 
routines are never referenced by the ReadScr1 source code. 

Thus, even if an include file incorporates a diversity of utility procedures and 
functions, it can still be used, without penalty, by applications requiring only a few 
of these provisions. 


Scope and the Pop_Directory Function 


Pop_Directory is, in effect, a subprogram within a function. It operates in an 
effectively autonomous fashion, handling its own screen displays, its own file I/O, 
and its own keyboard events, as well as declaring a number of constants, types and 
variables. 

Also like a program, Pop_Directory has a variety of subroutines—both proce- 
dures and functions—which are strictly local to Pop_Directory and cannot be 
referenced outside of this function. This restricted access is known as ‘scope’ and 
operates at all levels of programming. 

Scope has been mentioned previously, but this is the first example where it has 
been such an extensive consideration. In addition to the constants, types and 
variable declared within the Pop_Directory function, there are also thirty subrou- 
tines, including 24 procedures and 6 functions but not counting subroutines of 
subroutines. Because of scope, none of these elements can be referenced outside of 
the Pop_Directory subroutine. 

This restricted access is important because it is one of the advantages that allows 
a routine like Pop_Directory to act as an autonomous subprogram. Figure 16-1 
shows an overview of the primary source code file and the three include files used 
in the Pop_Dir example program, with shading showing the extent of the scope of 
elements from each portion of the program. 


292 USING TURBO PASCAL 6.0 








Within the Pop_Directory function are two subroutines that have their own 
subroutines. One of these declares a further subroutine, and each of these is also 
restricted in scope, functioning only in response to calls from their parent routines. 


An Exercise In Scope 


Now, in actual fact, it would be perfectly correct and valid to move a number of 
these subroutines—such as Pad, Write Date, Write Time, etc—outside of the 
Pop_Directory routine, for example, into the Frame.INC file or into a separate 
utility file. You might want to try this as an exercise: Move as many subroutines as 
practical out of the Pop_Directory function and into a new include file, where they 
can be used as general utilities. Before doing so, however, if you do not have the 
program disk with the source files for these programs, be sure that you have entered 
all of the program elements correctly and that the program compiles and executes 
correctly. Then use the Turbo Editor features to copy subroutines from the 
Pop_Dir.INC window to a new include file, making sure, of course, that the 
program continues to compile and execute correctly. 

This is not a frivolous exercise. It will show you what considerations are 
important in restricting scope, and, those subroutines that do not need to be 
restricted in scope can be useful utilities in other applications. 

A few hints: First, subroutines that use type declarations, constants or variables 
declared in the Pop_Directory function probably are not practical to move. In some 
cases, however, it may be worthwhile to redeclare the types or variables. Still, be 
careful. 

Second, subroutines that call other subroutines may or may not be moveable. 
Pay attention to what calls what. 

A third consideration is simply how general the employment of a particular 
subroutine is to other applications. If a subroutine is only useful within this 
particular scope, there isn’t really any point in moving it. 

Last, there are no answers to this exercise in the back of the book. The compiler 
and your own computer will grade your performance as well as point out the more 
blatant errors. For the more subtle errors, your own intelligence should be able to 
discover these. | 


Using Data Pointers 


The subroutine Read_Directory introduces another topic that has been discussed 
briefly in theory but is easier to explain in practice. 
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Pop_Directory reads a disk directory to create a list of files and subdirectories, 
which are presented in sorted order. The record structure SearchRec, which is used 
to read the directory, is predefined in the DOS unit. But, once the data has been 
read, this record type is too large for the information that needs to be kept in it, 
because the 21 byte Fill element is unnecessary. At the same time, it is too small, 
because for the purposes of this application, two additional word records are 
needed. This will be shown momentarily. 

In order to store the information this application will need to retain, we can 
define a new record type, ItemRec: 


RecPtr = “ItemRec; 
ItemRec = record 
Next, Prior <= Keertr; 
FileName : NameStr; 
FileExt : (EXtS Tr? 
FileAttr =: word, 
FileDate, 
FileSize =: lLongint; 
end; { record } 

ItemRec matches the SearchRec definition except for omitting the 21 byte Fill 
field and adding the Next and Prior pointer fields (4 bytes each), saving a grand 
total of 13 bytes. But more important than saving memory, the Next and Prior fields 
will be used to organize the information into a coherent order. 

As each directory entry is accessed by the Read_Directory subroutine, the New 
procedure allocates space in memory for a record of type ItemRec, and the infor- 
mation in the SearchRec record is copied to the new ItemKec instance—or, more 
accurately, into the memory location allocated for the new record instance. The data 
in the Fill field, of course, is omitted. 

Once this is done, however, the only way to access this record is by having a 
pointer that holds the memory address where the record has been written. 

One option would be to have an array of pointers indicating where the records 
are located in memory. This has some advantages over arrays of records, since a 
pointer array requires only 4 bytes for each reference, versus 26 bytes per record 
for an array of records, but it still requires a static array large enough to hold the 
maximum expected number of records. 

The array approach presents two problems: First, you must determine how 
many records is the maximum, and second, the memory required for either array 
is in use all the time, whether anything is actually written to it or not. 
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Rather than use an array, then, our application can expend only 12 bytes total 
by using three static pointer variables. These three pointers will be enough to keep 
track of an indefinite number of records, because we can let the records themselves 
keep track of each other. 

This is the purpose of the Next and Prior record fields, which are a part of each 
record. ! 

Figure 16-2 shows three data records, with the Next and Prior fields linking 
them together in a chain structure. The Firstltem and LastItem pointers point at the 
first and last of the chain of data. 


Figure 16-2; Tracking Records with Pointers 





Static Dynamic 
Memory 


Memory : 





This illustration is an oversimplification, however, because the records thus 
linked together are not necessarily located in any linear order in memory. In fact, 


they are probably not in any linear order, and they may not even be contiguous in 
memory. 
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Ultimately, however, the ordering of the records in memory is unimportant 
because we can create any order desired simply by linking the records in the desired 
order, or by using multiple links in several orders at once. This more complex 
approach will be illustrated later. For the present, we will use only a singly-linked 
and linearly-linked list. 


Creating a Linked List 


Pointer-linked lists hold a variety of attractions for the programmer. For one, linked 
lists are extremely efficient, not only from a storage viewpoint, but in sorting and 
accessing data. One big advantage is in sorting operations, because, even for 
inefficient sort routines, the data is never moved. Only the pointers ordering the 
data are moved. 

In this example, we will use an entry sort routine that sorts the data as it is read 
from the disk, thus minimizing the number of sort operations and, therefore, 
minimizing the time requirements. But before we describe a sort process for a linked 
list, let’s build a simple list without any ordering. 

Before we can construct this list—see the Read_Directory procedure—some 
preparation is necessary, beginning with three instructions to explicitly set the three 
global pointers to nil: 


FirstItem := NIL; 
MarkItem := NIL; 
LastItem := NIL; 


Even if this is the first time this routine is executed, there is no way to know 
what values these variables may hold unless an explicit assignment is made. 
Assigning these to nil ensures that they do not point to the wrong place, by explicitly 
pointing them to nowhere. (Note: The nil pointer holds the fixed address 
0000h:0000h.) 

A few other variables are also explicitly cleared at this point, and one pointer, 
Heap_Top, is passed as a parameter to the Mark procedure discussed in chapter 15 
to save the current heap state. Later, Heap_Top will be used to clear all allocated 
pointers even though, in other circumstances, more selective processes will be used 
to clear individual pointer records. 

Mark(€ Heap_Top ); c“maerk the stack «ae } 


DirSpec := DirPath + FileSpec; 
FindFirst( DirSpec, $3F, FileData ); 
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Next, a directory specification is established, using the current directory setting. 
Find First is called to get the first directory entry. 

As long as a directory entry is found, a loop continues, first calling the 
Add_Item subprocedure to store the entry found and then calling FindNext to get 
the next directory item. 


while DosError = 0 do 
begin 

Add_Item; 

FindNext( FileData ); 
end; 


The real work of creating the list is done in the Add_Item procedure, but just 
in case nothing has been found to match the file specification, a special pointer entry 
is set by the Null_ Pointer procedure. 


if FirstItem = NIL then { if nothing was found, 
Null_Pointer; { set up a null pointer 
end; 


Assuming that matching entries are found, however, the Add_Item procedure 
creates the desired list. 


procedure Add_Item; 
begin { create (allocate) 
New€ Newltem ); { to hold this item 


The first task undertaken by Add_Item is to allocate space to hold a list entry. 
This is accomplished by calling the procedure New with the pointer Newltem as a 
parameter. Since Newltem is a pointer to the record type that will be stored, this 
allows New to look at the record type and decide how much space will be required 
for a record. It then returns the address of the allocated space in the pointer variable. 

Next, the information read from the directory is copied to space just allocated. 
This instruction is a good example of how two different record specifications, 
FileData and Newltem”, can be referenced in a single with..do statement. Of course, 
it is necessary that the fields belonging to the two record types do not have any 
instances of the same name. 
with FileData, NewItem%* do 


begin 
FSplit€ Name, NullPath, FileName, FileExt ); 


then 


space 


yw 
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Because the with statement is used, the FSplit statement is the equivalent of the 
more verbose form: 


FSplit(€ FileData.Name, NullPath, 
NewIltem*.FileName, NewItem*.FileExt ); 


The variable NullPath is simply a string variable, which is necessary for this 
procedure call, but which will be ignored afterwards (and, under these circum- 
stances, should be returned empty anyway). 

The remaining assignments require little explanation. They simply copy data 
from one record to the other before adding the file size information to the total and, 
depending on the attribute flags, incrementing either the directory count or the file 
count. 


FileAttr = ATi? 
FileSize = Size; 
FileDate = Time; 


TotalSize TotalSize + FileSize; 
1f.Attr and $18 <> 0 then. tnetceteCount ? 
else inc(€ FileCount ); 
end; 


And now it’s time to begin building the list. 
The first step in building a list is the first entry, because initially, no list exists, 
and therefore, the first entry is a special case. 


if FirstItem = NIL then 


begin C-thts starts an empty list .s. } 
FirstItem := NewlItem; 
MarkItem = Newltem; 
LastItem = Newltem; 


LastIitem’®.Prior := NIL? 
LastItem*.Next := NIL; 
end else 


An empty list is initialized by pointing the three static pointers to Newltem and 
then linking LastItem’s Prior and Next pointers to nil. 

Notice that nothing was done to point FirstItem’s Prior and Next pointers 
anywhere. Why not? 

Of course, this is a trick question and you might pause for a moment and think 
about what is actually happening at this point. 

The trick is simply one of labels. FirstItem is only a pointer, just as LastItem is, 
and both are pointing to the same record structure as Newltem. However, because 
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there is only one record structure and one set of Next and Prior pointers, only one 

assignment is necessary. It could have been made using any of the three pointers, 

Firstltem, LastItem or Newltem to point to the single record while these assign- 

ments were made. This is really all that is necessary to initialize our pointer list. 
For a simple list with no sorting, the next entry read would be appended at the 

end of the list, thus: 

begin 


LastIitem*.Next 
NewIltem*.Prior 


Newltem; 
LastItem; 


First, Lastltem”.Next is pointed to Newltem or, more accurately, the Next field 
in the current LastItem record receives the address of Newltem. Remember, what 
we're really working with here are simply addresses of where data has been stored. 

Atthe same time, Newltem%.Prior is pointed to LastItem, and these two records 
are now linked together. 

But Newltem is now the item at the bottom of the list. Therefore, the next step 
is to point the static variable LastItem to Newltem. 


LastItem := Newltem; 
LastItem*.Next := NIL; 
end; 


The final step is to set LastItem”.Next to nil, which is exactly the same, at this 
point, as setting Newltem”.Next to nil. 

For a simple list without sorting, this is all that is necessary. After the list has 
been built, we can find any individual item by simply starting at the top of the list 
and moving down via the Next pointers until the desired entry is located. 

In this application, however, an unsorted list is not the objective, so the process 
of building the list must be slightly more complex. It must allow a choice of where 
each entry is placed in the list. 

Instead of simply tacking each item onto the end of the list, we can add 
provisions to insert an entry at the top of the list as well as at the bottom, and a 
further provision to search through and insert within the existing list. 

This also requires a mechanism to decide where an entry belongs. For the 
moment, the decision mechanism can be treated as a black box, which executes a 
comparison between two items and returns a true/false report. 

The first question that our entry-sort process has to determine: Does the current 
LastItem precede the current Newltem? 
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begin 
if Precede( LastItem, NewItem ) then 
begin { it goes at the END of List««s 3 


If this condition is satisfied, then the insert last provisions illustrated a moment 
ago will serve equally well in this version. 

If the test fails, we must determine if the current item belongs at the top of the 
list. 


end else 

if Precede( NewIltem, FirstItem ) then 

begin Tat goes @t the TOP of list... # 
NewIltem*.Next FirstIitem; 
FirstIitem’.Prior NewItem; 


For a new first item, the process is almost the same as for a new last item, 
beginning by linking Newltem’.Next to Firstltem and linking the current First- 
Item’.Prior back to Newltem. 

With these two links in place, the new entry becomes the first entry, and the 
Prior field is set to nil. 


Newltem; 
ae 


FirstItem 
FirstItem*’.Prior 
end else 


The toughest case is not the first or last but when the entry needs to be fitted 
somewhere within an existing list. For this circumstance, we need one additional 
pointer. The global (to this function) pointer, ThisItem, is available, but, instead we 
will use a local pointer named MarkItem (remember, pointers are cheap). 

MarklItem is set at the top of the list, but as soon as the loop begins, it is stepped 
down one, which is fine since the first entry has already been tested. 


begin 
{ not first or last so. we'll have to start at the top } 
{ and search down the List of entries until found ... } 
MarkItem := FirstItem; 
repeat 


MarkItem := MarkItem%’%.Next; 
until Precede( NewItem, MarkItem ); 


The loop steps down the list until an entry in the list is found that should follow 
NewEntry. 
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Now that the right position has been located, in this situation, we need to relink 
four pointers. More important, we must do it without losing any existing links, 
because once the chain is broken, there is no way to link up again. 


NewItem*.Next 
NewIltem*.Prior 


MarkItem; 
MarkItem*.Prior; 


Thus, the first step is to link Newltem’.Next to Markltem and link New- 
Item’.Prior to Markltem”.Prior. This establishes two of the links, one forward and 
one backward. Therefore, Newltem now has a grip across the point where the chain 
needs to be broken. 

At this point, MarkItem can be forgotten and, since Newltem”.Prior references 
the preceding item, Newltem”’.Prior’.Next references the preceding item’s Next 
field, which is linked back to Newltem. 


NewIltem’%.Prior’.Next 
NewItem*%.Next*%.Prior 


NewIltem; 
Newltem; 


Finally, the remaining link is referenced in the same fashion, first going forward 
through an existing link and then referencing the Prior link backwards. 

This insert process could be done in several fashions—or, at least, using several 
different reference pointers, but the essence of the process remains the same: You 
begin by setting links with the new record and then use these links to reset the 
existing links. 


Ordering the List 


Ordering the list is a special trick in this example, because two different criteria are 
used to decide on the ordering. The first criterion is to put all root, subdirectory or 
volume label entries at the top of the list and then follow with the file entries. 

Note: If you would like to see the order in which the directories are actually 
read from the disk, just comment out the test conditions and let the list assemble in 
the order read, as shown for the unordered example. This should show a pretty 
mixed list, because, unless some utility such as a backup has recreated the directory 
order, both subdirectories and files appear in the directory table in the approximate 
order of their creation. 

This is only an approximation, however. Deleted directory entries may be 
replaced by new entries, as the disk operating system simply seeks the first 
available space for each item. 

The Precede function can impose any order desired. 
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function Precede( Ptri, Ptr2: RecPtr ): boolean; 
begin 

Instead of deciding in advance which data elements will be used to determine 
the ordering, the Precede function is simply passed the two pointer values and then 
decides on its own which data is relevant. 

In this fashion, several different sort options can be exercised, even though only 
one is provided here. 

The tests are relatively simple. They begin by determining if the two entries 
being compared are directory or volume label entries or not. It doesn’t matter, just 
as long as both are the same type. If so, a simple comparison of file name plus file 
extension determines the ordering. 


if€ Ptr2*.FileAttr and $18 ) = 
C Ptr1* FiteAttr ene $16.4 
then 
Precede := ( Ptr1*%.FileName + Ptri*%.FileExt ) < 
C Ptr2*.FileNane + Ptr2* FiteExt 2? 


If the attribute flags are different for the two items compared, then a different 
test is used, comparing the attribute bytes. 

Precede := ( Ptri%.FileAttr and $18 ) > 
C PtrZ> .FiAtedttr and Sits); 

Notice, however, that the Archive, Read-only, System and Hidden attribute 
flags are ignored in all of these tests, and results are determined only by the 
Directory and VolumelD flags. 

The result of the sort operations is shown in Figure 16-3, which illustrates the 
directory display positioned at the right of the screen. The background shown is 
provided simply to illustrate how an existing screen display can be saved and 
restored. 


The Pop_Directory Display 


The Pop_Directory display consists of a frame and three main windows, beginning 
on the left with the file display window, where the current selection is highlighted. 
You can use the cursor controls—the up and down arrows, PgUp, PgDown, Home 
and End keys—to move through the list and scroll the window as necessary. 
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Figure 16-3: The Pop_Directory Display 
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The current drive and path specification is shown at the top of the frame, while 
the upper right window shows the file specification, the number of files and 
subdirectories in the current list, and the total size of the listed files. 

The lower right window provides information about the current file (high- 
lighted), including file size and the date/time stamp, as well as statistical informa- 
tion about the selected drive and the system memory. 

Below the Pop_Directory frame, a prompt appears: Fl = Help. Pressing F1 
summons the help display shown in Figure 16-4, which provides a list of the 
currently supported options. 


Supported Options and Features 


When you press the Enter key the present version of the Pop_Directory function 
responds in two different fashions, depending on the nature of the highlighted list 
item. If the current selection is a root directory or subdirectory, the Enter key is taken 
as an instruction to change directories. 

Alternately, if the current selection is a file entry, pressing the Enter key exits 
the Pop_Directory function, returning the selected drive/path/filename to the 
calling application. 
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Figure 16-4: The Pop-Up Help Display 
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Pressing Ctrl-P calls the ““Path only” option, exiting the function but returning 
only the current drive/ path specification and not returning a filename. 

The final exit option is exercised by Ctrl-Q, which simply calls for an exit 
without returning anything (i.e., returning an empty string). 

Aside from the return (exit) options, four additional features are supported, 
beginning with Ctrl-D, which calls the delete option to erase the current file or 
subdirectory. However, this is subject to some restrictions (see the Delete Option, 
below). 

Ctrl-F calls a dialog permitting entry of a new file specification. Ctrl-L permits 
logging a new active drive. 

The final option is a fast-search provision. Pressing any alphabetical key (A..Z, 
a..z) initiates a search through the list for the first entry with a matching or greater 
first letter. Note: this is one of the areas where a number of revisions are not only 
possible but very desirable. Deciding how to improve this feature is up to you and 
your needs, design and investigation. Figuring it out will be a useful exercise. As 
is, it does work, but it can also work much better. 

Another fact to recognize is that the help message box is also a pop-up, as are 
several other dialog or error boxes. These also use the Save_Screen and 
Restore Screen procedures to restore the directory display when finished. 








The Delete Option 


The Delete option supported by the Pop_Directory subroutine has to handle two 
different circumstances: deleting subdirectories and deleting files. 

If the selected item is a subdirectory, Turbo Pascal’s RmDir procedure is the 
obvious choice. Aside from a dialog display asking for confirmation and an error 
message display if deletion fails, removing a subdirectory is relatively straightfor- 
ward, Remember, however, that only an empty subdirectory—one with no files or 
further subdirectories—can be removed. 

The second case is deleting a file. This can be accomplished using Turbo Pascal’s 
assign and erase procedures, beginning by assigning the desired path/file as an 
untyped file and then, without calling reset or rewrite, exercising the erase proce- 
dure. The only restriction is that read-only files cannot be deleted unless the file 
attribute byte is changed first. 

Pop_Director, however, takes a different approach. The Pop_Directory Delete 
option (implemented by the Delete_Current_File subroutine) uses the DOS inter- 
rupt (21h) function 41h, as shown below. 

Before calling the interrupt function, a complete file specification is required, 
but with one difference, which isn’t customary in Pascal but is often required by 
interrupt functions dealing with strings: 


DelFileStr := DirPath + DelFileStr + #$00; 


The DOS interrupt function expects to find the drive/path/filename supplied 
as a null-terminated string, also known as an ASCIIZ string format. To provide this 
format, the first step is simple: Append a null character as the final character in the 
string. 

The second step in supplying an ASCIIZ string parameter is to pass the string 
in a form that does not include the first byte, which, in Pascal, is the string length 
specification but is not a part of the drive/path/ filename. 

This is easily accomplished, however, simply by how the parameter is passed. 

When calling interrupt functions, the only provisions for passing information 
are by loading word or byte values in the registers. This is certainly not directly 
compatible with passing a string argument. But passing the string argument 
indirectly—by address—is a different matter. It can be done using the ofs and seg 
routines. 


with Regs do 
begin 
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{ point to buffer } 
{ holding filename } 


ofs€ DelFiteStrt ti: 2 
seg( DelFileStr(f€1J] ) 


DX 
DS 


The offset of the address is a word argument. It is passed to the DX register, 
while the segment address is passed to the data segment (DS) register, also as a 
word argument. Together, they tell the interrupt function where to find the string 
argument. 

Instead of using these to pass the address of the string itself, however, which 
would be the address of the first character of the string (DelFileStr[0]), the string 
length character needs to be skipped. Therefore, the address passed is the address 
of the second string element (DelFileStr[1]), which is the first character of the actual 
string argument. 

Since the length of the string is not provided, this should explain why the null 
terminator was required. 

Note: Any reader who uses or has used the C programming language, should 
recognize a familiar string format in this interrupt call, because this is exactly how 
C implements strings. 

Aside from reformatting the string parameter to match DOS expectations, the 
rest of the interrupt call consists of loading the function number in the AH register 
and calling the msdos procedure. 


AH := $41; , function 41" } 
msdos( Regs ); { interrupt 21h 


Y 


Since this operation is being carried out through an interrupt call, the result of 
the operation is returned in the AX register and in the Carry flag, which is set (1) if 
the operation was not successful. 


Result += Lot. Ak-~23 { test result } 
if Flags and FCarry = O then { delete okay } 


If testing the Carry flag reveals an error, an error message is displayed. 


An Alternative Delete Function 


Either the Turbo Pascal erase procedure or the delete function illustrated will return 
an error if an attempt is made to remove a ‘read-only’ file entry. At the same time, 
the means supplied by Turbo Pascal for changing file attributes—see GetFAttr and 
SetFAttr—require that the file be assigned to a file handle. 

Using DOS interrupt calls, as demonstrated, interrupt 21h, function 43h can be 
used to reset file attributes. 
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Alternatively, the entire delete file process can be rewritten using a Turbo Pascal 
file handle and assigning the filename as an untyped file, while making additional 
provisions to detect and alter ‘read-only’ flags. 

Therefore, if you wish to keep the delete option in this feature, your assignment 
is to use either approach—employing interrupt calls or using Turbo Pascal file 
operations—to construct a new file delete process that accomplishes the following 
tasks: 


Detects read-only flags before attempting file deletion 
Queries deletion for read-only files 

Changes file attributes as necessary 

Carries out the deletion process 

Reports the results 


oO aie ee a 


You could also add a new option to change file attributes for any file without 
involving a delete operation. 

Note: The Directory and VolumeID attributes cannot be assigned to files, and 
cannot be changed on existing directories or volume label entries. Directories, 
however, can be assigned the Hidden attribute. 


Cleaning Up the Heap 


Each time the Read_Directory subprocedure is called, Mark(Heap_Top) is executed 
to store the current heap pointer before space is allocated for the file list entries. The 
Display Directory subprocedure concludes with the instruction Release(Heap_ 
Top), which resets the heap pointer, disposing of the current file list. 

Since the present application does not expect intensive changes to a list after it 
is created, the mark and release approach to memory management is fine. 

Any deletions from the list are handled by the Remove_Item subroutine, which 
simply links around the cancelled entry but does not deallocate the memory used 
by the entry, leaving memory management for the end of the operation. 

In other circumstances, managing a list needs a more sophisticated approach 
to handling memory allocation, beginning by deallocating memory for any list 
deletions. 

The current handling in the Remove_Item procedure, simply relinks the list 
pointers without deallocating memory for the cancelled entry. This is a good place 
to begin improving memory management, starting by adding a local pointer 
variable: 
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procedure Remove_Item; 
var 
MarkItem : RecPtr; 


Now when Remove_Item is called, the first step should be: 
MarkItem := ThisItem; 


With this provision, even after the list has been updated and ThisItem has been 
reassigned to a new list item, the pointer variable MarkItem still holds the address 
of the discarded list entry. 

Therefore, at the end of the Remove Item subroutine, after the list has been 
relinked, one further instruction is all that’s necessary to release the memory 
presently allocated for the old list entry. 


dispose( MarkItem ); 


In actual fact, this same task could also be accomplished without creating a local 
pointer by simply calling one instruction at the beginning of the Remove_Item 
procedure, thus: 


dispose( Newltem ); 


In general, deallocating the memory for a list item before relinking the list is 
considered poor programming. However, calling the dispose procedure does not 
change the data in memory; it only updates the DOS memory allocation tables to 
say that this region in memory is now free and can be reused. 

As long as the pointer values that were stored here are copied to other point- 
ers—which is the task accomplished by relinking the list—before this area in 
memory is overwritten, this is perfectly safe. 

Either approach can be used, but you should exercise the second approach with 
a bit more care. 

You might experiment with this change first. Call the MaxAvail and MemAvail 
functions to see how holes are being created in the heap each time an item is deleted. 

Remember, the mark and release calls presently used will continue to clean up 
the entire heap, and memory allocation tests must be executed before this is done. 


Replacing the Mark and Release Calls 


The mark and release procedures are only useful when entire blocks of memory are 
being released. Many applications, however, may need to be more selective. For 
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example, an application might maintain more than one linked list and need to be 
able to deallocate one list while not affecting another. 
Alternatively, other memory allocation processes might be operating at the 
same time that could be adversely affected by calling the release procedure. 
Therefore, the next step should be to erase the mark instruction in the 
Read_Directory subprocedure and to replace the release instruction in the Dis- 
play_Directory subprocedure with a new set of instructions: 


ThisItem := FirstItem; 
repeat 
FirstItem := ThisItem*.Next; 
dispose( ThisItem ); 
ThisItem := FirstIitem; 
until Firstitem = nil: 
end; 


This set of instructions steps down through the pointer list, disposing of each 
item in the list, until the end of the list is reached. The big difference between this 
and the mark / release system is that this process releases only memory allocated 
to items on this list and does not affect any other memory allocations that may have 
been made. 


Summary 


The Pop_Demo program and the three include files demonstrate how programs 
can be subdivided and how utility subroutines can be collected in include source 
files for use in developing multiple applications. Also, the ReadScr1 program 
makes a second call to the Pop_Up.INC file, demonstrating another method of 
using pointer assignments. 

The Pop_Directory function itself demonstrates the construction of a relatively 
complex subprogram, as well as providing a variety of useful subroutines. 

Handling the directory lists read by Pop_Directory provides a hands-on illus- 
tration of a basic pointer-linked list—which is, at once, both the most difficult and 
one of the most useful applications of pointers. 

However, the Pop_Directory function itself is not provided as an instant, 
pop-this-in-your-program-as-is utility. This can be a beginning for your own 
design, but this book is not a cookbook. The Pop_Directory utility is not polished, 
nor even 100% debugged. This is a deliberate exercise in programming; what you 
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will learn by investigating and correcting this program will be of far more value 
than any ready-to-use utility. 

Anumber of improvements and alterations have already been suggested in this 
chapter, some of which may be more relevant in other applications than here. But 
they still demonstrate how alternate approaches can be used. This is important, 
because there are no single best ways that fit every application. 

Linked lists themselves are a major programming development which can be 
used in a wide variety of applications for a wide variety of purposes. However, the 
only linked list shown thus far is a linearly linked list. A more efficient form known 
as a binary tree will be demonstrated later in the form of a binary-tree object, a new 
development, which not only manages its own memory allocation but is also able 
to execute its own sorting and many other operations. 

For the present, however, the complete source code for the Pop_Demo.PAS, 
Frame.INC, Pop_Up.INC, Pop_Dir.INC and ReadScr1.PAS files follows. These can 
also be found on the program disk available for this book. 


{sess2resscsszessesess} 
{ Pop_Demo.PAS } 
{ woses Roop.) ThctNe 2 
{=sSeeeanascscesessssseze } 


uees Crt, Dos; 
{$I POP_DIR.INC} 
var 


1; £ Bytes 
Selection : string: 


begin 
TextAttr := $6F; 
cCtrsers 
for i := 1 to 74 do write( ' Background screen display '); 
TextAttr := $OF; 
Selection := Pop Directory 60, -'%,"%'. 07 


TextAttr t= SOF; 
gotexy<t 10, 18 23 
writet.': The selected file is ', Seteetion,:.*." 2; 
readln; 
end. 
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{SI FRAME.ANC: >} 
{$I POP.UPCING 3 


{Sesesseseseeeeresesezseeescaszes=s) 
{ Pop_Dir.INC } 
{SesSeseeSeeeee2 ee see 2225222) 


{ draws box frames for display 
{ provides save screen procedure, 


} 
etc} 


functton Pop_Directory( Of fSet: byte; DirSpec: string ): 
strind; 
const 
KByte 1024; 
NullStr = 'S==NO=FILES=='; 
Accent_Color = Red * LightGray shl 4; 
SideBar_Color = Blue * LCYQGAtGray sht° 46>: 
Norm_Color = Yellow + Black shl 4; 
Border_Color = LightBlue + Black shl 4; 
Border_Accent = Red * Black shl 4; 
type 
WindCnt = (€ WMain, WList, SideT, SideB, PopWd ); 
STR20 = stringl20J; STR12 = stringli2] + 
SsTRe.-@stringle.: 
RecPtr = “ItemRec; 
ItemRec = record 
Next, Prior RecPtr; 
FileName NameStr; 
FileExt ExXtStr: 
FileAttr word; 
FileDate, 
FileSize Longint; 
end; {record} 
var 
FileSpec STR12; TotalSize real; 
Regs registers; Heap_Top “integer; 
PopUp, Complete boolean; 
FirstItem, LastItem, ThisItem RecPtr; 
CurDrive, DirCount, FileCount, Row, i integer; 
Select_File, Original_Path, OldFile, DirPath Patnstr: 
procedure Set_Window(€ WindNum: WindCnt ); 
begin 
case WindNum of 
WMain: begin { Main Window 
TextAttr := Norm_Color; 
Wincowt : TH#O0t7Set> 3 1, 40407 fSet, 25 2 
end; 
WList.: Window. 2¢0tfSet) “2, Beeotrset; 23. d; 


SideT: Window( 24+0ffSet, 
SideB: Window( 24+0ffSet, 
PopWd: Window( 24+0ffSet, 
end; {case} 
end; 
function Pad¢t Num: byte ): STR2Z 
var 
Temot  STRE> 
begin 
str€ Numid, Temp 2; 
if TempC1] = ' ' then Templ1 
Pad := Temp; 
end; 


procedure Write_Date( FileDate: 


var 
DateRec datetime; 
begin 
unpacktime( FileDate, DateRe 
with DateRec do 
writet Month:2, ‘7, Pea 


end; 


procedure Write_Time( FileDate: 


var 
DateRec datetime; 

begin 
unpacktime( FileDate, DateRe 


with DateRec do 


writet HoursZ2, "3s", Paactn 


end; 


procedure Frame_Screen; 


var 
I integer; 
begin 
Set_Window( WMain ); 
TextAttr := Border:_Cotlor; 
cLPSscr? 
Box Line€ ty te 60s 24. 23 
V Linet 235 -tx cee 22 
H Linet 23, 8; 4 3; 
gotoxy( 4, 1 22 


TextAttr 
TextAttr 


Border_Accent; 
Border_Color; 
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Se7+OTTSet, ‘TT J; 
S9+OTT Set. bed: 
S9+OTT Set, 25 (73 


7 


J 
Longint ); 


ae EE 


Day2, o'7*t, PadCYear-1900) )->; 


Loridint 3; 


ey 


fer 34. PaatSec2d 2: 


{ frame for directory popup } 


wreytet he "hs 
writeC DirPath )d; 


wre: ie), 
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TextAttr := Border_Accent; 
SOtOxyYC Ty 2a. 2p en teeve! ET Ss Betp th 3d 
end; 


procedure Side _Bar_2; CTT on fects on current Titec? 
begin 

Set_Window( SideB ); 

TextaAttr =:= SideBar._Color; 


GOLOSYS\: Oy Te es weet *Careent: Fite’): 
COLTON. £66.92) MPVREOt Sizes cor oe 
GOteeyc 8, S32: er itee: S¥tes' Dz 
gotoexy< 25° 4°) 5: wrireet* Petes") che 

GOtOxy. 259.72 “urttets* Times * os 

with ThisItem* do 

begin 


TextAttr := Accent.:Cotor; 
if FileAttr and Directory <> 0 then 


begin 
gotoxy(: 2, 2.73. writet:'Otrectory or eRe &- 
gOotoxyt 2, 3 ds writet  ‘Seb<PDirectory * 2; 


end else 
if FileAttr and VolumelID <> O then 
begin 


Setoxy( 2,2 92: wer ter! “Votume lebet *)2 
S0toaxyt 2, 3°23 er Peet) setae oF 
end else { not directory or volume label, } 
begin { ergo, must be regular file } 
Botoxy(  45..8 3% Write t:(FT Caest 20:9. .):s 
SOtoxry( fy £24 if FileSize > KByte then 


wr itet CPT Lesize / KByte 263 1 d:3 
end; 
gGotoxy( 86, 4 3; Write Date( FileDdDate. >); 
gGotoxyt 6, 5 )2 Write.Timet Filedate ): 


end; 
end; 
procedure Side_Bar; { main display for directory popup } 
var 
DskFree, DskSize : Longint; 
pegin 


Set_Window( SideT ); 

TextAttr := SideBar_Color; 

cLirecr? 

gotoxy( >) 2223 Wereet <Vettespec: =! .s; 
gotoxy( Oy AAO he rE eet oh ht lags} 
gotoxy(¢ a, 9 2p Werte *Otnaectonted' >): 


gotoxy ( a 6 
TextAttr = Acc 
gotoxy( 14-leng 
gotoxy( ae 4 
gotoxy ( ta 5 
gotoxy( 8, 6 
DskFree := Disk 
DskSize := Disk 
TOXTACtr 22-Sid 


Set_Window( Sid 
eLrecr; 
gotoxy ¢ 
gotoxy( 
gotoxy( 
gotoxy(¢ 
gotoxy ( 
gotoxy ¢ 
gotoxy ¢ 
TextAttr 
gotoxyt 12, 
gotoxy ¢ 
gotoxy ¢ 
gotoxy ¢ 
gotoxy( 
gotoxy(¢ 
end; 


= 
Oo On 


FNNWDNDYDYED LS 
ee ee 
= W PM 


Or SS A ee ee 


Acc 


F-wWONUO ON 


—_ «dt ood 


procedure Write_En 
const 
AttrFlag arra 
ae 
var 
i: integer; 
begin 
with WhichItem*% 
begin 
Set_Window ( 
gotory¢ 2, 
gotoxy( 10, 
gotoxy( 15, 
fT. FU LEACEF 


begin 
if FileAt 
begin 


write ( 
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1 * wMpotet- theta ks eee 
ent..Cotor? 
CHS Ftvespec >, 3S 22 
CWEVTeC CES CPS laespec; - te" * >> 
ae WEES ORA EACH nt!3S Fs 
>? weitet BPirCount:3s >; 
ee weteet C:fetalSize / 1024.0-)3:6:0 dF 


Free( CurDrive ) div 1024; 
Sizext Curdrive 2 div. 0242 
eBar._Color; 


eB ); 

2s NOTA be ive. = ' ->e 

a2 wet tet *Stzes are ee 

ds 'writet ‘Used: ae 2. 

ds write( *Frees K-23 

); write(€ 'System Memory' : 

Y; write( ' Free: ae &- 

72 writet "Bléck: m= 22 
ent_Cotory; 

ye WpPitet chert Curd riveree pots" D> 
>: writed DskSizer6é >)»: 

»; write ¢€ DskSize - DskFree ):6 ); 
Je weitet BskFree:6- )} 

); write(€ € MemAvail div 1024 ):5 ); 
PS wr ltet Ce Peek vatt div 1024 +35 Dd» 
try( WhichItem: RecPtr; YPos: integer ); 


yCO0.,51 of stringess 


a vets Hy, "Four, ‘otr* AS 8 
do 

Ieee 

YPos ); write€ FileName ); 

YPos )>; writeC FIleExt 33 

YPos ); 


and AnyFile <> O then 


tr and $18 <> O then 
{ clears attribute byte } 
{ on volume Label entry } 


‘Cc! bm 
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FileAttr := FileAttr: and $18; 
end else write( ‘'<' ); 
TOPrit +2. 0°: t9° 3; qo 
FP FtlLeAtte;: and «S07 -eneet 2: <> 
then wrtteC Attfrrtagt+2 > 
1f FileAttr and $18 <> 0 
then wrttet 427) vet se wrttet.'>* 
end; 
end; 
end; 


procedure Blank_Entry( YPos : integer ); 
var 

1°23: Fategqer ; 
begin 

Set _Window( WList ); 

gotaxyt:"1, Y¥Pos 7: 

Tor F424. to. 20 Co. wPritecaw sy 
end; 


procedure Hi_Light_Current; 

begin 
TeXtAttr: +3 AecentCotor; 
Blank_Entry( Rowt1 );3 
Write Entry€ ThisItem, Rowt1 ); 
Side: Bar. 2: 

end; 


procedure Lo_Light_Current; 

begin 
TextAttr := Norm_Color; 
Blank_Entry( Rowt1 ); 
Write_Entry( ThisiItem, Row+1 ) 3; 

end; 


procedure Pop_Boxt TitleStr: string 2; 


begin { create box for 


PopUp := True; 
Hic LAgat:-Current; 
TextAttr := Border_Accent; 
Set_Window( SideB ); 
clrse¢r?; 
Set _Window( WMain ); 
Boe. inet 243, 6, 60,2640 4 

Wha nee 2S, 70; 40-37 

Center tines: 24 83 39s TVtteste 3: 


message } 
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Set_Window( PopWd ); 
end; 


procedure Command_Help; 


procedure Show_Prompt( VPos: byte; PromptStr: string ); 


var 
I : integer; { print one character } 
begin { at a time and change } 
gotoxy(. 1, VPos D: 1) £610F TO SOCent «ss 2 
for I := 1 to. tengthtPromptstr) do 
begin 
1f Prose tstrEl] in Cte ea 2g OF A 
then TextAttr := Border_Accent 
else TextAttr := Border_Color; 
wrtteC “cooyet Promptstr,: tp, %. ? 22 
end; 
end; 
begin { Command Help main } 


Pop_Box( 'Commands' ); 
Show_Prompt ¢ : 22 


<L>ettaer for*. 2; 
Show_Prompt( 11, feet search’. 77 
Show_Prompt( 13, dee 2 
while not keypressed do; 
end; 


' 
Show_Prompt ¢ a ADelete' ); 
Snow _Promett “3, * AFile-spec' ); 
Show_Prompt( 4, ' ‘Loe @Prive*- zs 
Show_Prompt ¢ a “Rath oniy'*: >> 
Show_Prompt ¢ oy a ae 
Show.Prempett: $f, ° .* 33 
Show _Promptt 9, * or enter" 22 
Show Prompt .:.10, ¢ 

' 

' 


function Check_Drive: integer; 
begin 

Regs.AH := $19; 

intrt S2t, Rees: 2%; 

Check_Drive := Regs.AL + 1; 
end; 


returns 0 = As, 1 B: but } 
we want 1 = A;, 2 Br, eta 
because zero reserved for. } 
undefined (default) drive } 


"oss WC oon Yell ome I ae 


function LogDrive( NewDrive: char ): boolean; 
var 

NewDir : string; 
begin 
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NewDir := NewDrive + ':\'; 
{$I-} ChDir(€ NewDir ); {$I+} 
if I0result = 0 then 


begin 
CurDrive := ord( NewDrive )-$40; 
DirPath = NewDir; 


LogDrive := True; 
end else LogDrive := false; 


end; 

procedure Null_Pointer; { this is used when } 

var { netning se Lett to 3 
NuliPtr: s: RecPtr; { point at } 

begin 


New( NullPtr ); 
Null Ptr*. FileName 
NullPtr*. FileExt 
NullPtr’*. FileAttr 
FirstItem := NullPtr; 
Firstitem*®:. Prior := Null Ptr; 
FirstItem*.Next := NullPtr; 
LastItem := FirstItem; 
ThisItem := FirstItem; 

end; 


copy(: Nultste;- 15.8) 
copy( Nutistr, 3, 4 2 
$00; 


“we Ne 


procedure Read_Directory; 
var 
FileData : SearchRec; 
DirSpec : PathStr-; 
NewlIltem, 
MarkItem : RecPtr; 


procedure Add_Item; 
var 


Null Path: DirStr; 


function Precede( Ptri, Ptr2: RecPtr ): boolean; 
begin 
LTC Ptr’]*. Fi teaAttr and $18.) = 
CPST FTL LeAtt rR. ahd $18 > 
then 
Precede := ( Ptr1*.FileName + Ptri*.FileExt ) < 
C Ptr2*. FileName + Ptr2*.FileExt ) 
{ if directory and volume attribute bytes are } 


{ the same then sort by file name and extension } 
else 


Precede 
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-= ( Ptr1*%.FileAttr and $18 ) > 
C Ptr2crileAttr and 26 >?; 


{ attr bytes different, sort vol and dir first } 


end; 
begin { create (allocate) space } 
New( Newltem ); { to hold this item } 


with FileData, NewlItem%* do 


begin 


FSplit( Name, NullPath, FileName, FileExt ); 


FileAttr 
FileSize 
FileDate 
TotalSize 


ALE? 
Size; 
Time; 
TotalSize + FileSize; 


if Attr and $18<> 0 then inc( DirCount ) 


end; 

if Firstitem 

begin 
FirstItem 
MarkItem 
LastItem 


LastItem% 

LastItem% 
end else 
begin 


else inc(€ FileCount ); 
{ update total i 


= NIL then 
{ this starts an empty List ... } 
Newltem; 
NewIltem; 
NewIltem; 
~PPior 32 Nit; 
-Next := NIL; 


if Precede( LastItem, NewIltem ) then 


begin 


{ it goes at the END of list... } 


MarkItem := LastItem; 
LastItem*.Next := Newltem; 
LastItem := Newltem; 
LastItem’.Prior := MarkItem,; 
LastItem*.Next := NIL; 


end else 


if Precede( Newltem, FirstItem ) then 


begin 


{ it goes at the TOP of list... } 


MarkItem := FirstIitem,; 
FirstItem*.Prior := Newltem,; 
FirstItem := Newltem; 
FirstItem*.Next := MarkItem; 
FirstItem*.Prior := NIL; 


end else 
begin 


{ not first or last so we'll have to start at the top } 
{ and search down the List of entries until found 
MarkItem := Firstitem,; 
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repeat 

MarkIt 
until Pre 
NewItem*% 
NewItem%’. 
NewItem%’. 
NewItem*%* 


end; 
end; 
end; 
begin 
FirstItem := NIL; 
MarkItem := NIL; 
LastItem := NIL; 
DirCount := Q; 
FileCount := 0Q; 
TotalSize := Q; 


tA 
Mark(€ Heap_Top ); 
if DirPathC ord( D 
then DirPath 
DirSpec DirPath 
FindFirst(€ DirSpec 


while DosError = Q 
begin 
Add_Item; 
FindNext( FileD 
end; 
if FirstItem = NIL 
Null_Pointer; 
end; 
procedure Up_Line; 
begin 
if ThisIltem <> Fir 
begin 
ThisItem 3:= Thi 
dec(€ Row ); 
if Row < O then 
begin 
Row := QO; 
eotoxy< 1, 7 
InsLine; 
Write_Entry(¢ 
end; 
end; 


end; 


-Next 


»~Next*. Prior 


em MarkItem*.Next; 
cede( NewIltem, MarkItem ); 
MarkItem; 

Prior MarkIitem*.Prior; 
Prior*’.Next Newltem; 
Newltem; 


{ Read_Directory } 


{ start everything clear and } 
{ mark the stack } 
TOR@EHEOD i) Dd ee 
DITPSethn + OVE 
+ Fitespec: 
, SSF, FileData’)s 
do 
ata--?3 
then { if nothing was found, then } 
{ set up a null pointer } 
stIltem then SOUT Net ae toe of List > 
sItem*’.Prior; { move current to prior } 
{ move row marker up } 
{ above top of window } 
{ reset counter } 
i { position cursor } 
{ make new Line } 
THRISF TOM, k 2 { and write it } 
{ otherwise, the highlight is enough } 
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procedure Dn_Line; 


begin 
if ThisIltem <> LastItem then {:4F not at end of List } 
begin 
ThisItem := ThisItem*.Next; { move pointer down one _ } 
inc(€ Row ); { move row marker down } 
if Row > 21 then { past bottom of window} 
begin 
Row := 21; { reset counter } 
gotoxy( 1, 22-34 { position cursor } 
writeln; € serott-up one tine } 
Write Entry(€ Thteitem, 22 ); { and write entry } 
end; 
end; 
end; 
procedure End_Of_List; 
begin 
Set _Window( WList ); 
while ThisItem <> LastItem do Dn_Line; 
end; 
procedure First._of_Lists 
begin 
Set_Window( WList ); 
while ThisItem <> FirstItem do Up_Line; 
end; 
procedure Update_Screen; 
var 
i: integer; Final : boolean; Temp_Ptr =: RecPtr; 
begin 
Temp_Ptr := ThisItem; { use an expendable pointer } 
Final := false; 
for i := Rowt1 to 22 do { from current item down } 
begin 
if not Final then Write_Entry( Temp_Ptr, i ) 
else Blank_Entry( i ); 
if Temp_Ptr <> LastItem . not et. end of List } 
then Temp_Ptr := Temp_Ptr%.Next { move temp_ptr down } 
else Final := true; { else set flag } 
end; 
end; 


procedure Write List: 
begin 
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thse Mails D5 eel RE OT ES a OO neces LSrOSPOnNT NOE ceca 


Side_Bar; 
ThisItem := 
Row := O; 
TextAttr := Norm_Color,; 
Set_Window( WList ); 
Update_Screen; 


FirstItem; 


TF OOLAGET te (<s0"*. Bhen 
repeat 
Dn_Line 


unt+ie post OUdFite,. Thisitem 
or(€ ThisItem = LastItem ); 
OldFite 22 **; 
end; 


procedure Remove_Item; 
begin 
Set_Window( WList ); 


if ThisIltem*.Prior = NIL then 
begin 
if ThisItem*.Next = NIL 


then Null_Pointer 
else 
begin 
ThisItem := ThisItem%’.N 
Thisitem’.Prior :2: NTL; 
FirstItem := ThisItem; 
end; 
end else 
if ThisItem*.Next = 
begin 
ThisItem := ThisItem’*.Prio 
ThisItem*.Next := NIL; 
LastItem := ThisItem; 
dec(Row); 
end else 


NIL then 


with ThisItem%*% do { 
begin 
Next*.Prior := Prior; { 
Prior*®.Next :2= Next; { 
ThisItem := Next; { 
end; 
Restore_Screen( 2 ); 
PopUp := False; 


Update_Screen; 
end; 


{ make sure ThisIltem and 
{ row point to the top 


C put the. list (on :ecreen 


A,.FileName ) <> 0 ) 


{ reset OldFile to null 


{ and Update List 


Cat the top: of the tist 


Left 
create null pointer 


{ but there's nothing 
{: 80, 


ext; { step down one and 
{ delete pointer previous 


{ and reset FirstItem 


{ at the bottom of the 
Pip { step up one 


List 
item 

{ delete pointer next 

{ reset LastItem 

{ and move Row up 
must be somewhere in middle 
point next_prior to cur_prior 
point prior__next to cur__next 
and reset cur to next item 
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procedure Delete_Current_File; 


var 
DelFileStr : PathStr; Result : integer; 

begin 
Pop_Box(€ ‘Delete File’ ); 
DelFileStr := { get filename only } 


ThisIltem*.FileName+ThisItem*.FileExt; 
1f ThisItem® .FileAttr and $18 <F20 then 


begin {oT not regular file J 
writeln; 
writeint * ', DelFitestr Be 
writeln(€ ‘' is a directory' bg 
writeln(€ ' or volume Label' ); 
writeln; 
writeln(¢ ' Confirm' oF 
writeln( ' Deletion?' ); 
write , Yes CNG): 33 
Check_Kbd; 
if upcase(Ch) = 'Y' then { ask before delete } 
begin 
{S$I-} RmDir( DirPath + DelFileStr ); {$I+} 
if I10Result <> O then { test 10Result ... } 
begin 
writeln; writeln; 
writeln(¢ ' ', Pecrrtestr ri: 
writeln(€ " must be empty' i; 
writeln( ‘before’ detetion’ d; 
while not KeyPressed do; { just wait for key } 
end else 
begin 
dec( Dircount -)3 { delete okay, } 
Remove_Item; { clear it } 
end; 
end; 
end else < it’s #@ 7 eaulter file so + 
begin 


writetns 

writeln( ' Contirm' 23 

writeing * deletion. for’ :.2z 

writetnat © <';° Petia tlestry, :*s" . 23 
| 


write ( Yes/t(No)* 23 

Check_Kbd; 

if upcasetCh) = ‘YY then { delete confirmed .«.. } 
begin 


DelFileStr := DirPath + DelFileStr + #$00; 
{ interrupt expects a null terminator} 
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with Regs do 


begin 
DX 3 of SC: DEtFILeStredva.. ay 
DS := seg( DelFileStr(C1J] ); 
AH := $41; 
msdos(€ Regs ); 
Reagult == Lot AX. 25 
if Flags and FCcarry.&287tten 
begin 


TotalSize := 
TotalSize - 
Geet: Fa letount. 2s 
Remove_Item; 
end else 
begin 
writeln; 
urirtetnat * trror 
case Result of 
2 writeln( ! 
Sh wettest.) 
| 
' 


7" > 


et wer ee tae 
else writeln(¢ 
end; {case} 
while not KeyPressed do; 
Check_Kbd; 
end; 
end; 
end; 
end; 
if FileCount+DirCount = 


Side_Bar; 
Set_Window( WList ); 
end; 


procedure Fast_Search( Key: 
begin 
Lo Light. Current: 
if Key > ThisItem*%.FileNamel[1] 
then 


chara 


Result 


tte ' not: found". 2 
path not found' 
access denied' 
unlisted error' 


0 then Nult.. 


{-potat to buffer 
{ holding filename 
{ function 41h 

{ interrupt 21h 

{ test result 

{ delete okay 


{ deduct from total 


ThisIltem*%. FileSize; 


{ and decrement count 
{ delete failed! 


).; 


{ DOS flag returned 


ae 
+; 
1} 


{ wait for key 


Pointer; 
{ no entries displayed 


{ key says forward 


while( ThisItem*.Next <> NIL ) and 


( Key > ThisItem*.FileNamel[1] 
do Dn_Line 
else 


) 


{ key says back up 


while€ ThisItem*.Prior <> NIL ) and 


( Key <= 


ThisItem*’.Prior*.FileNamel[1] ) 


Wwe e Ye Ye 


end; 


function Check_Selection: boolean; 


var 


selection +: STR2ZQ: 
CheckVal : boolean; 


begin 
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do Up_Line; 


is this a directory 
or a filename or is 
this time to reset 
the file spec? 


"con Toon YE ae YO oa 


CheckVal := False; 
with ThisItem%* do 


Selection := FileName + FileExt; { get current item 
if Selection = NullStr then 
begin 
riteSpec se **,*"s { reset file spec 
CheckVal := True; 
end; 
if ThisItem*.FileAttr and Directory <> O then 
{ this is a directory 
begin eS WISH. Peet. or e0b°? 
CheckVal := True; {. but, ar ets set flee 
if Selection£Ltiy = '.*. then { must be root 
begin 
OldFile := DirPath; { copy path to OldFile 
repeat { trim path back to next \ 
Geletet DirPath, oraC: -DirPathi0] 3), 1 Iz 
until DirPatht ordt DIFPaetate? 23 = 'N\" 3 
OldFile := 
copy( OldFile, lLength(DirPath)+1, 11 ); 
delete( OldFile, lLength(OldFile) , 1 ); 
1 triemciest char ¢\) 
{ DirPath now refers to root of present directory 
{ OldFile holds present directory name only 
end else { wasn't the root 
begin t.must be subatraes. 
while pos(€ ' ', Selection ) > O do { delete blanks 
deletet Selecticn, post." *, Setection ), 1 D3 
DirPath := DirPath + Selection; 
end; 
end; 
Check_Selection := CheckVal; { return flag value 
end; 


function ChangeFileSpec: boolean; 


var 


New_Spec : stringl121]; 


begin 


Wey wy 


Ww YY YY 
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Pop_Box('FileSpec'); 
writeln; 
writeln(€' <ENTER> = 
wraitetint? FiteSpec:'); 
write (' she BF - readln(New_Spec); 
Set_Window( WList ); 
if New_Spec = '' then New_Spec := 
if New_Spec <> FileSpec then 
begin 
FileSpec := New_Spec; 
ChangeFileSpec := true; 
end else ChangeFileSpec := 
Restore_Screen( 2 ); 
PopUp := False; 
end; 


Ws 


false; 


function Change_Drive: 
var 
New_Dir: 
begin 
Pop_Box('Disk Drive'); 
writeln; 
write(€'Select drive: 
Check_Kbd; 
Set_Window( WList ); 
1%: wpeeeeCehein CATA TET a 
then Change_Drive 
else Change_Drive 
Restore _Screen( 2 ); 
PopUp := False; 
end; 


boolean; 


string; 


a: 


false; 


procedure Display_Directory; 
var 
Done 
begin 
Seleet Fite ee '"s 
Write_List; 
Done := false; 
repeat 
if PopUp then 
begin 
Restore_Screen( 2 ); 
PopUp := False; 
end else Hi_Light_Current; 
Check_Kbd; 


boolean; I integer; 


, { set wildcard 
{ if there was change 


{ assign to FileSpec 
{ and set flag true 
{ else set flag false 


{ could be a valid drive 


{ 


{jetenrt<6tt -asg 


LogDrive( upcase(Ch) ) 


invalid flag false 


an empty string 
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Save_Screen( 2 ); 

case UpCase(Ch) of 

#$00 begin 
Lo Light._current: 
case KCh of 


#$4B, 
4349s for 1 (25° 4: te 27. ao 
#$4D, 
#SS51: for 1°33 St-f6ea rode 
#$50: Dn Line: 
#$48: Up_Line; 
HS4Gf: First OF. Liane 
AS4F: End OT: t7 8%: 
#$3B: begin 
Command_Help; 
PopUp := True; 
end; 
end; {case} 
end; 


{ Control characters are used for 


#$O04: Delete _Current_File; 
#$06: Done := ChangeFileSpec; 
#$OC: Done := Change_Drive; 
#SOD: if Check_Selection then 
Done := True else 
begin 
with ThisItem%* do 
Select_File := FileName 
while: pos€.-':'; uSetectFile 
delete( Select_File, 
bose eos 
Select_File := 
Complete := True; 
end; 
#$10: begin 
Select_File := DirPath; 
Complete := true; 
end; 
#$11: begin 
Select Fite cs: "*s 
Complete := true; 
end; 
{ ASCII characters provide fast 
'A',.'Z*s Fast. Search upceset--tn. 
end; {case} 


until(€ Done or Complete ); 





Setect.Fite 2d, 1 
DirPath + Select_File; 


{ save this display 


{ special key 
{ Left 
PgUp 
Right 
PgDn 
Down 
Up 
Home 
End 
F 1 


Up_Line; 


Dn_Line; 


AAA AAA AA 


qdtrectory functions 


C70 Detete file 

“. “F Title spec 

{ *k. Aogiodrive 

{ CR Enter key 

{ change directory 
{ return item now 


+ FileExt; 
) + OD -€6 


i; 


{ *P filepath only 
{92 wat, reture 
{ null selection 


search options 
); 


ee ee ee ee 


Ww Ww ww YY Ww 
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{ Done allows exit to Loop in main 
{ Complete allows exit from loop in main 


Release(€ Heap_Top ); { release memory used by List 
end; 
begin { Pop_Directory main 
Save_Screen( 1 ); 
CurDrive := Check_Drive; { get currently logged drive 
GetDir( CurDrive, Original_Path ); { and directory path 
DirPath := Original_Path; { save current drive/path 
if DirSpec = "then OldFite geet tC: nutl OldFite 
else 
begin 
14-9060 *\" 5 Birspec..> <> 2 then 
begin 
OLarite s=2 * "> 
white DirSpecl ord Dirspeclas:):.3 <><" Vv" do 
begin 


Oldfile := DirSpeclCord(DirSpeclOJI3] + OldFile; 
{ copy directory name to OldFile 
detetet DirSpec, ordGotrspeclOd),. 1 2; 
{ and delete from DirSpce 
end; 
DirPath := DirSpec; 
end else OldFile := DirSpec; 
end; 
PopUp := False; 
Complete := False; 
FItespec t= '* 4" 5 { wildcard as initial file spec 


repeat 
Frame_Screen; 
Read _ Directory; { repeat loop until user exits 


Display_Directory; 
until Complete; 
Pop_Directory := Select_File; 
Choirt:-Griginatl Path. 2; 
WERGOWE. Ts BU, 23. 22 
Restore_Screen( 1 ); 
end; 


check filename to return 
reset to orig drive/path 
reset orig window size 

reset orig video display 


a 


YY 


ee 


Wee wye 
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(SsSesSeS2eeeeeeeseeeeee=e=z===} 
{ FRAME.INC } 
{ frame outline procedures’ } 
(SSsSS2eSeeeee822e2eeee2ee=e=e==} 


procedure Box_Line(€ XAxis1, YAxis1, XAxis2, YAxis2 : byte ); 
const 

BoxStr : stringl6] = #SCO+HSCD+HSBB+HSBA+HSCBE+HSBC; 
var 


+ &£ bytes 
begin { start at: the: top. 
gotoxy XAxisi, YAxist)s write(€ BoxStrC€1J ) 


for 1 s= XAxislt + 1 to XAxte2d: +1. ¢6 writet BoxsStrf2] ): 
wrTtex® BoxsStr(si dv: 
{ add the sides } 
for i := YAxis1 + 1 to YAx?s2 =—=a6 


begin 
gotoxyt XAKist, 1°23 write(. Boxstrec4é] d>: 
gotoxy( XAxis2, i ); write¢ Bexsétr(4J] >: 
end; 


{ and finish the bottom } 
gotoxy( XAxTe4 5 YAX1T82" > write€ BoxStrC€5J] ) 
for 1 = XAxis1 * 1 ‘to Radxetet =— 7 do write( BoxStrf€2] ) 
write( BoxStrl6] ) 


“we “Se Se 


end; 


procedure H_Line€ XAxis1, YAxis, XAxis2 : byte ); 
var 


+ = byte: 
begin 
gotioxyt XAxiset, YAx18<.22 write( #SCC*)>: 


for i := XAxis1+1 to XAxis2-1 do write( #$CD ); 
write( #$B9 ); 


end; 


procedure V_Line(€ XAxis, YAxis1, YAxis2 : byte ); 
var 

1 + Bytes 
begin 

gotoxy( XAxis, YAxis1 ); write( #$CB ); 

for i := YAxis1 + 1 to YAxis2 -1 do 

begin 

gotoxy( XAxis, i 23; write( #$BA ); 

end; 
gotoxyt XAxte, YAR s2 33 write C #$CA 2; 
end; 
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procedure Box_Window( XAxis1, YAxis1, XAxis2, YAxis2, FColor, 
BColor: byte ); 
begin 
Window 1, 13°30; 255 23 C weset to fault - screen) 
TextAttr := FColor + (€ € BColor and $07 ) * $10 ); 
Béxctinet. XAxiet,. YAxts%,: KAet62,  YAR1s2 2; 
Window .XAxK1S141,  YARES1TSO1, XA S2-1,. YAxis2=1. 0; 
clrscr? { create the new window inside the border } 
end; { and erase new window } 


procedure Center_Line( XAxis, YAxis, Limit: byte; 
Centerstr: string); 


var 
Lif Fnteger; 
begin 
gotoxy( XAxis,. YAx1s 23 
for 1°25 2AR4 ss. to Lindt GO- wrt ret hs." }3 
gotoxy( XAxis + CLimit-XAxis-ord(CenterStrlOJ)+1) div 2, 
YAX36: 2 
write ( benterstr b 
end; 
{ssseeseseneeseeeece=)} 
{end of: FramevInc : } 
{szesaeseseeeesesseece= } 
{sesssetsescresasastseeeeseescecesess} 
{ POP_UP.INC } 
{ pop_up procedures used to } 
{ save existing screens, etc. } 
{seseessesezesseasssaueeezeseseeeses=)} 
type 
Sereen = erreyl 1. <25, 1..80: 1 of: word; 
ScrPtr = “Screens 
var 


MonoScreen : Screen absolute $B000:$0000; 
ColorScreen : Screen absolute $B800:$0000; 
KeepScreen : arrayl1..2] of Screen; 
Activescreen =: SerPtr; 
ColorVideo : boolean; 
Chis Rent -thar? 


procedure Save_Screen( ScrNum: byte ); 


begin 
ColorVideo := (€ LastMode 
if ColorVideo then 
KeepScreenl ScrNum J] 
KeepScreenl ScrNum J 
end; 


procedure Restore_Screen( ScrNum 


begin 
if ColorVideo then 
ColorScreen := 
MonoScreen 


end; 
procedure Set_Color( Color: 
begin 

if not ColorVideo and 


( Color and $80 = $80 
COoLor t FT UU; { 
TEXTATi <= Cotor: 


end; 


procedure Test_Mode; 
begin 

if LastMode = 

then ActiveScreen := 

else ActiveScreen := 


Mono 


KeepScreenL 
KeepScreenl 


instead of blink, 
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<> Mono ); 


ColorScreen else 
MonoScreen; 


byte ); 


ScrNum J] else 
ScrNum J; 


byte ); 
{ color passed as byte 
{ is system monochrome 
») then { is blink turned on 


use black on white 


aMonoScreen 
aColorScreen; 


end; 
function Read_Screen( XPos, YPos byte ): char; 
begin 
Read_Screen := chr( loC€ ActiveScreen*E YPos, XPos J] ) ); 
end; 


procedure Check_Kbd; 


{ Ch & KCh are global variables 


begin 
Ch := readkey; £ reternvJAStll: values tin Ch 
if Ch = #00 { if it's an extended key 
then KCh := readkey { return extended key in KCh 
else KCh := #00; { otherwise set to null 
end; 
{sceseseseztsesrezasesaers} 
{ end Pop_Up.INC } 


wey YH 


wy 


kyl hgh Gy Oy 
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{seseeeesesssrrssesseesesss=e==a} 
{ ReadScr1.PAS } 
{ demonstrates direct screen } 
{ read utility routines } 
{sseeeesessscesesesseressss=sz=} 
uses Crt? 
{$I POP_UP.INC} 
var 
14: 4} se AR eer 
begin 
cire<cr:? 


gotoxyt 1, 1°); 
Tor 4: 52 4: to. 5 do 
for i. 2:2: 7 to 80 do 
write( chr( random( 26 )+64 ) ); 
writeln( 'The preceding five Lines were', 
' randomly written®' ); 


{ read and copy five Lines from existing screen display } 


Test_Mode; 
goteuy (oT 55:.10 2% 
writeln( 'The first five screen Lines are read as:' ); 
Or Fite tT to: 3:40 
Tor si56 8) te. 80: eo 
write( Read _Screen( i, j ) ); 
readln; 
end. 


Chapter 17 


Units and Overlay Operations 


In Chapter 16, we need include files to collect subroutines that could be employed 
in creating more than one application. The limitation of an include file, however, is 
that the source code in the include file is recompiled every time it is called by an 
application that is being compiled. Turbo Pascal provides an alternative to overlays 
in the form of units, to get around this problem. 

Units have already been introduced in our discussion of library units, specific- 
ally the Crt and DOS units, where so many of the functions we have used are 
located. Turbo Pascal also allows you to create your own, custom units, which can 
be called and employed in the same fashion as the supplied library units. 

The main difference between a unit and an include file is that a unit has already 
been compiled. A second difference is demonstrated later in this chapter, when 
units are used for overlays. 

Creating source code for a unit is extremely simple. Using the Pop_Up.INC file 
from Chapter 16 as an example, only a few changes are necessary before this can 
be compiled as a custom unit. 

As a matter of fact, the changes are so simple that, instead of changing 
Pop_Up.INC at all, we can create a new file as Pop_Up.PAS, which consists of the 
changes that we would have made, plus its own include statement to call 
Pop_Up.INC for the implementation portion of the code. 
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Creating Units 


The revisions required to create a unit consist of three primary elements. The first 
element is simply a unit heading, which is declared by the reserved word unit and 
appears as: 


unTt: Pop Up? 


The unit heading must be a unique name, which will be used in refering to the 
unit in subsequent uses statements; two units with the same name cannot be used 
at the same time. The length of the name is a maximum of 8 characters, and the 
.TPU extension is used for all units. 

A potential conflict arises here because the unit name declared by the unit 
statement does not determine the name of the file. The compiler creates an output 
file with the same name as the source file but with the extension .TPU, and this is 
how another program looking for the unit will search for the compiled file. But the 
application using this unit will also expect to find an internal name that is the same 
as the unit’s filename, but is the string specified by the unit statement. 

To avoid compiler errors, be sure that the unit name and the filename of the 
unit source code match. 


The Unit Interface Section 
Next, we declare the interface section, using the reserved word interface: 


interface 


Following the interface declaration statement are all constants, types, variables, 
procedure and function names, and so on that are public—i.e., available to the 
programs or other units that will be using this unit. 

Remember, any element that is not declared in the interface portion of the unit 
cannot be referenced outside of the unit. Therefore, in this example, the declarations 
for all of the procedures and functions are listed here as public declarations. In this 
fashion, other programs can call these routines by name. 

Any variables, data or record types or constants that would be used outside of 
this unit would also be defined here. 


procedure Save_Screen( ScrNum: byte ); 


procedure Restore_Screen( ScrNum : byte ); 
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procedure Set_Color( Color: byte ); 
procedure Check_Mode; 
function Read_Screen( XPos, YPos : byte ): char; 


procedure Check_Kbd; 


The Unit Implementation Section 


The third section is the implementation section, again declared by a reserved word, 
implementation. Everything declared in this section is private and cannot be 
accessed directly outside of the unit. 


implementation 
uses Crt; 


{$I Pop_Up.INC } 


In this example, the implementation section of the unit consists of a single uses 
statement, which is necessary because procedures within the unit will refer to the 
Crt unit for definitions. In previous examples using Pop_Up.INC, no uses state- 
ment was necessary in the include source code because this was supplied by the 
main source code. But, for this to be compiled as a unit file, all references must be 
satisfied at compile time. Also, since this uses statement appears in the implemen- 
tation section, which is private, it is invisible to other code using Pop_Up.TPU. 

The second statement is simply an include statement calling the Pop_Up.INC 
file. This is precisely the same as if the Pop_Up.INC file had been copied directly 
into this source code but saves providing two versions with duplicated code. 

The procedure and function headings that appear in the interface section can 
simply be repeated in the implementation section in full, or they can omit the formal 
parameter list. For example, where the Read_Screen function heading appears in 
the interface section with a complete parameter list, thus: 


function Read_Screen( XPos, YPos : byte ): char; 


in the implementation section, the parameter specifications and the return value 
specification can be omitted: 


function Read_Screen; 
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However, when the full specification appears in both places, the compiler issues 
an error message if the interface and implementation declarations fail to match. 


The Unit Initialization Section 


A fourth part of a unit is known as the initialization portion of the unit. It may 
include a statement part, which is executed to initialize the unit. 

In practice, the initialization part of a unit is usually omitted, except for the 
reserved word end. by itself: 


end. 


In our Pop_Up unit, however, the initialization section might include the 
following instruction: 


begin 
ActiveScreen := nil; 
end. 


This would initialize the unit pointer, ActiveScreen, to ensure that it is not 
pointed somewhere in never-never land. With this provision, it would also be 
possible to revise the Read_Screen function to execute its own test to ensure that 
the current video mode is tested at least once. 


function Read_Screen; 
begin 

if ActiveScreen = nil then Check_Mode; 

Read Screen := chr( lo(€ ActiveScreen“LYPos,XPos] ) ); 
end; 


Even better, the Check_Mode provisions can simply be incorporated into the 
initialization portion, thus: 


begin 
if LastMode = Mono 
then ActiveScreen 
else ActiveScreen 


aMonoScreen 
aColorScreen; 


end. 


In this fashion, the Check_Mode procedure can be deleted from the unit source 
code, and ActiveScreen will be automatically assigned to the appropriate memory 
location without requiring any initialization provisions by applications using the 
unit. 
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Units can also include circular references, where two or more units refer to each 
other. This is a special case, where units are created that are mutually dependent 
and require some special handling. Refer to the Turbo Pascal Programmer’s Guide for 
further details. 


Overlay Programming 


In Chapter 16, we used include files, in part, to reduce the size of unwieldy source 
code. But another problem with size can occur when the compiled program itself 
becomes too large to operate in available memory, or becomes so large that the 
program does not leave enough free memory for necessary data. 

When either problem occurs, Turbo Pascal provides a solution in the form of 
overlays. 

Overlays are sections of code that can be swapped in and out of active memory 
as specific routines are needed. In general, the best performance is provided when 
overlays consist of associated subprograms. For example, the Pop_Directory func- 
tion demonstrated in Chapter 16 would be appropriate for an overlay unit because 
it is essentially self-contained; it can be loaded into active memory, used, and then 
discarded in favor of another unit until it is needed again. 

On the other hand, libraries consisting of mixed subroutines used by many 
different areas of an application are less appropriate for an overlay. An overlay unit 
of this type would be loaded repeatedly as different processes required features 
located in the subroutine. This does not, however, mean that such an assembly 
should never be used as an overlay. 

In the final analysis, which portions of a program should be created as overlays 
depends entirely on the application. The best general rule is to try to keep associated 
subroutines together, creating several smaller overlay units rather than one or two 
large catch-all overlays. 


The Overlay Manager 


The overlay manager is implemented by the Overlay unit, providing both flexible 
and efficient overlay performance within the available memory limits. 

In Figure 16-1 (previous chapter) the overlay buffer was illustrated as a block 
of memory allocated between the stack and the heap. The overlay buffer is space 
allocated by the overlay manager. By default, it will be the size of the largest overlay 
used, though explicit instructions may be used to increase the buffer size. 
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Regardless of the buffer size, however, the overlay manager keeps as many 
overlays as possible in the buffer, to reduce the time required for loading overlays 
from the disk. Also, the overlay manager provides facilities for EMS support, 
allowing the overlay file to be loaded into expanded memory if sufficient space is 
available and an L/I/M 3.2 or later EMS driver is loaded. Once the overlay file is 
transfered to EMS, subsequent overlay loads are executed as fast, in-memory 
transfers between EMS and the overlay buffer. Once an overlay in loaded to the 
buffer, calls to overlay routines execute at the same speed as non-overlay routines. 

When loaded overlays need to be removed from the buffer to make room for 
new overlays, the overlay manager disposes first of inactive overlays (overlays 
without currently active routines). 


Compiling Units for Overlays 


Before a compiled unit can be used as an overlay unit, two directives must be 
included in the unit source code. In addition, a couple of other elements which may 
be factors in how the unit can be used must also be included. 

First, all overlay units must include the {$O+} directive, which instructs the 
compiler to generate code that can be overlaid. 

Second, calls to overlaid procedures or functions must use the far call model, 
which is set by the {$F+} directive. 

For the overlay unit, both directives can be specified in a single statement as: 


{$O+r, Fr} 


At the same time, any non-overlay units, as well as the main program, should 
include the {$F+} directive to force far calls for all procedures and functions. 

Warning: If you do not observe the far call requirements when writing overlaid 
programs, results may be unpredictable, and/or critical errors may occur during 
execution. 

To simplify things, you may include these same directives, {$0+,F+}, with all 
units compiled, and the units can then be used either as overlay units or as 
non-overlay units, with the decision for each unit made by the program employing 
the unit. 


Calling Overlays 


Once a unit has been compiled appropriately for use as an overlay, the calling 
application may use the unit either as an overlay or as a conventional unit. For 
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either usage, of course, the program employing the unit must begin by including 
the unit name in the program’s uses statement. Note that if any of the units 
employed will be used as overlays, the Overlay unit must also be included in the 
uses statement, and must precede any overlay unit names. 

For example, a program using overlays might look something like this: 


{$F+} 


uses Crt, Dos, Overlay, ExOne, ExTwo, ExThree; 


Notice that the {$F+} directive appears at the beginning of the program, prior 
to the uses statement, and forces far calls for all procedures and functions. 

The uses statement declares the units that will be used placing the Overlay unit 
prior to the overlay units. The non-overlaid unit references—including Overlay— 
may occur in any order. The only restriction is that the Overlay unit references must 
be listed somewhere after the Overlay reference. 

Following the uses statement, the {5O unitname} statements specify which units 
will be employed as overlays: 


{$0 ExOne} 
{$0 ExTwo} 
{$O ExThree} 

The main program then begins with the OvrInit instruction, which initializes 
the overlay manager and creates an overlay swap file: 
begin 

Ovrinit¢ “Exanpte.OVR* J; 

After this point, the program can continue with no further explicit overlay 
provisions. It is a good idea, however, after calling OvrInit, to call OvrInitEMS, so 
that, if EMS memory is available, the entire overlay file can be loaded into EMS for 
faster access. 


Overlay Units with Initialization Sections 


Units incorporating an initialization section, as suggested for the Pop_Up unit, can 
be used as overlay units but do require a special provision to initialize the overlay 
handler before the unit initialization attempts to execute. 

If a unit containing an initialization section is referenced by the uses statement, 
and then by the {$O overlay directive, the initialization section attempts to execute 
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immediately as an overlay. This causes a system error, halting further execution 
because the overlay handler is not yet active. 

To prevent this problem, you can incorporate a special, non-overlay unit. It 
should appear in the uses statement after the Overlay unit and before any of the 
overlay units. This unit would consist of nothing except an initialization section: 


unit InitOvr; 
interface 
implementation 
uses Overlay; 
begin 
OvriInit( ‘ReadScr3.0VR' ); 

The filename specification provided by OvrInit, of course, has to match the 
name of the program that is using the InitOvr unit, because, at compile time, all 
overlay units are written to a single execution overlay with the same name as the 
program, but with the extension .OVR. 

An alternative to separate overlay files appears later in the section “Patching 
Overlays Into .EXE Files.” 


OvrInitEMS; 
end. 


Since the initialization section of this unit is executed immediately after it is 
loaded into memory, other units containing initialization sections can also execute, 
even though they are loaded as overlays. 

However, overlaid initialization code is not recommended for general use, 
because, first, the initialization code is executed only once though it is still a part of 
the overlay and occupies overlay buffer space. Second, if multiple overlay units 
have initialization code, each of these will have to be loaded into memory when the 
program starts. 

The alternative approach is to put all initialization code in a single, separate 
unit, which can be called once at the beginning of the program and then forgotten. 


Overlay Restrictions 
A few restrictions on overlays must be observed: 


« Units compiled in the {$O-} condition cannot be used as overlays. 
Attempts to do so will result in a compiler error. 
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» Of the standard units, the DOS unit can be used as an overlay, but the 
System, Overlay, Crt and Graph units cannot be used as overlays. 

« Units containing interrupt handlers cannot be called as overlays, due to 
the non-reentrant nature of DOS. However, don’t confuse interrupt han- 
dlers with interrupt calls. For example, the Crt standard unit implements 
a Ctrl-Break interrupt handler, which redirects the DOS Ctrl-Break inter- 
rupt handler, and therefore, cannot be overlaid. All units, however, use 
DOS interrupt calls to accomplish various tasks, and these do not pres- 
ent the same conflict. 

» Units using BGI drivers and fonts registered with calls to RegisterBGI- 
driver or RegisterBGIfont cannot be overlaid. 


Overlay Debugging and Profiling 


While many debuggers have little or no overlay debugging support, both the Turbo 
Pascal integrated debugger and the Turbo Debugger provide full overlay support. 
With either the integrated or standalone utilities, debugging overlays is completely 
transparent, with no special requirements. 

The Turbo Profiler also provides full support for programs using overlays, with 
the single restriction that code views are not available for overlay units that are not 
presently loaded in the overlay buffer. 

For either Profiler or Debugger operations, however, the overlay code does 
need to be in a .OVR code file rather than patched into the .EXE file (see next 
section). The reason this restriction is imposed is simply that debug information 
must be turned off for the main program before the overlay files can be appended. 

For more information on both debugging and profiling programs in general, 
refer to my previous book, Using Turbo Debugger and Tools 2.0 (Addison-Wesley, 
1990). 


Patching Overlays Into .EXE Files 


Normally, when a program using overlays is compiled, the overlay units are 
combined in a single file with the same filename as the .EXE program, but with the 
extension .OVR. The OvrInit instruction specifies the overlay file for loading. As an 
alternative, after compiling, the .OVR file can be appended to the .EXE file using 
the DOS COPY command with the /B command-line switch. This provides a 
distinct advantage for distributed programs, since the end user is not required to 
keep track of both the .EXE and .OVR files. 
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Before this can be done, however, two specific requirements must be met: first, 
the OvrInit instruction needs to call the .EXE file instead of the .OVR file. For 
programs operating under DOS 2.x or earlier versions, you can simply change the 
file extension name in the source code. For programs operating under DOS 3.x or 
later, the ParamStr function can be used, thus: 


OvrInitt ParamsStrtd) d; 


Second, the .EXE file must be compiled without Turbo Debugger information, 
which is process and address information appended to the end of the compiled 
.EXE file. When using the IDE compiler, go to the Options / Debugger dialog box, 
and be sure that the Standalone option is unchecked. Using the command-line 
version of the compiler, be sure not to specify the /V switch. 

After compiling, the .OVR file can be appended to the .EXE file using the DOS 
COPY command, as, for example: 


COPY/B EXAMPLE.EXE + EXAMPLE.OVR 


The /B command switch instructs COPY to treat the files as binary rather than 
text files. In this form, COPY uses the actual file size, in bytes, as specified in the 
directory. Otherwise, COPY would treat the files as text files and terminate each at 
the first Ctrl-Z (1Ah) byte encountered. (The Ctrl-Z character is used as an end-of- 
file marker in text files.) 

Remember, both provisions must be exercised before the compiled program 
can be tested in the new format. 


Overlay Procedures and Functions 


The Overlay unit provides several procedures and functions, which are detailed in 
the following dictionary listings: 


Ovrinit Procedure Overlay 
Ovrlnit initializes the overlay manager, opening the overlay file. 
Declaration: OvrInit( FileName: string ); 


The overlay manager is implemented in the Overlay unit and must be initial- 
ized by calling the OvrInit procedure before any overlay operations can be used. 
The FileName parameter specifies the filename where the overlay portion of the 
program code is found. If FileName does not include a drive or directory specifi- 
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cation, the overlay manager searches for the overlay file first in the current direc- 
tory, then in the directory where the .EXE file was called, and last, by searching 
through the directories in the PATH specification. 

Possible error codes are ovrError and ovrNotFound. If an error occurs, the 
overlay manager is not installed, and subsequent attempts to call overlay routines 
result in run-time error 208. 


OvrinitEMS Procedure Overlay 
The OvrInitEMS procedure attempts to load the overlay file into EMS memory. 


Declaration: OvrinitEMS; 


If OvrInitEMS is successful, the overlay file is closed, and all subsequent overlay 
loads are executed as fast in-memory transfers. If OvrInitEMS fails, the overlay 
manager continues to function, but overlays are read from disk. 

Note: OvrInitEMS does not eliminate the overlay buffer located between the 
stack and heap in DOS memory. Overlays must still be copied from EMS into the 
lower 640K of RAM before they can be executed. The advantage lies simply in the 
speed of in-memory transfers versus reading from the disk. 

Possible error codes are ovrError, ovrlOError, ovrNoEMSDriver and ovrNo- 
EMSMemory. 


OvrSetBuf Procedure Overlay 
The OvrSetBuf procedure sets the size of the overlay buffer. 
Declaration: OvrSetBuf( Size: longint ); 


The buffer size specified must be larger than or equal to the initial size of the 
overlay buffer (see OvrGetBuf) and less than or equal to MemAvail plus the size of 
the current overlay buffer. 

OvrSetBuf requires that the heap be empty at the time of the call. An error 
message is returned if dynamic variables have already been allocated on the heap 
using New or GetMem. 

If the size specified is larger than the current size, additional space is allocated 
from the beginning of the heap, decreasing the size of the heap. Likewise, if a 
smaller size is specified, the excess space is returned to the heap. 
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Possible error codes are ovrError and ovrNoMemory. If an error occurs, the size 
of the overlay buffer remains unchanged. Operation of the overlay manager is not 
affected. 


OvrGetBuf Function Overlay 
The OvrGetBuf function returns the current size of the overlay buffer. 
Declaration: vrGetBuf: longint; 


When an overlay program is executed, the initial overlay buffer is as small as 
possible, corresponding to the size of the largest individual overlay. 


OvrClearBuf Procedure Overlay 
The OvrClearBuf procedure clears the overlay buffer. 
Declaration: vrClearBuf; 


The OvrClearBuf procedure clears all currently loaded overlays from the 
overlay buffer, forcing subsequent calls to overlaid routines to reload the overlays 
from the overlay file or from EMS. 

OvrClearBuf is never called by the overlay manager. It decreases performance 
of an application since it forces overlays to be reloaded. But it does provide a means 
to empty the overlay buffer, allowing memory to be temporarily reclaimed for other 
uses. 

If OvrClearBuf is called from an overlay, the overlay is reloaded immediately 
on return from OvrClearBuf. 


OvrSetRetry Procedure Overlay 


The OvrSetRetry procedure sets the size of the “probation area’”’ in the overlay 
buffer. 


Declaration: OvrSetRetry( size: longint ); 


The OvrSetRetry procedure is provided for optimizing overlay buffer usage, 
but the default probation area size is zero, effectively disabling the proba- 
tion/reprieval mechanism. 

The probation area is used to optionally prevent frequently called overlays from 
being bumped from the buffer, thus requiring reloading for subsequent calls to 
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overlay routines. Probation area sizes in the range one-half to one-third of the 
overlay buffer size appear to provide the best results. 

Further information on the probation/reprieval mechanism can be found in the 
Turbo Pascal Programmer's Guide. 


Example: 

OvrInit( '"MYPROG.OVR' ); 
OvrSetBuf( BufSize ); 
OvrSetRetry( BufSize div 2 ); 


OvrGetRetry Function Overlay 


The OvrGetRetry function returns the current size of the probation area as a longint 
value. 


Declaration: OvrGetRetry: longint; 


Overlay Constants and Variables 

The Overlay unit also defines several variables that can be used to track overlay 
operations: 

OvrResult Integer Overlay 


Before returning, each procedure in the Overlay unit stores a result code in the 
OvrResult variable. OvrResult is similar in application to the [OResult function 
except that OvrResult is not reset to zero after access. 

Possible return codes are defined in Table 17-1. 


Table 17-1: Overlay Result Codes 


Constant Value Explanation 

ovrOk 0 No error 

ovrError —] Overlay manager error 

ovrNotFound —2 Overlay file not found 

ovrNoMemory —3 Insufficient memory for overlay buffer 
ovrlOError —4 Overlay file 1/O error 
ovrNoEMSDriver —5 EMS driver not installed 


ovrNoEMSMemory- -6 Insufficient EMS memory 
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OvrTrapCount Word Overlay 


OvrTrapCount is initialized with a value of 0. When a call to an overlaid routine is 
intercepted by the overlay manager, either because the overlay required is not 
presently in memory (needs to be loaded) or because the overlay is on probation, 
OvrTrapCount is incremented. 


OvrLoadCount Word Overlay 


OvrLoadCount is initialized with a value of 0. Each time an overlay is loaded, 
OvrLoadCount is incremented. 

The OvrTrapCount and OvrLoadCount variables might be examined using the 
debugger’s watch window to monitor the frequency of calls and overlay load 
operations. This information might be used to study the effects of different buffer 
size settings, changes in probation area sizes, or even revisions in overlay unit 
organization to optimize operations for an application. 


OvrFileMode Byte Overlay 


The OvrFileMode variable controls the DOS file access code for the overlay file. The 
default value is 0, corresponding to read-only access. If a different access code is 
desired, to provide shared access on a network system, for example, OvrFileMode 
should be changed before calling OvrInit. 


OvrReadBuf OvrReadFunc; Overlay 
OvrReadBuf is a procedure variable, defined as: 


type 

OvrReadFunc = function(€ OvrSeg : word ): integer; 
var 

OvrReadBuf : OvrReadFunc; 


OvrReadBuf permits intercepting overlay load operations so that, for example, 
a check can be run for a removable disk (i.e., is the overlay file present in the active 
drive?), or so that other custom error handling can be implemented. 

Whenever the overlay manager needs to load an overlay into the buffer, it calls 
the function whose address is stored in the OvrReadBuf variable. If this function 
returns a non-zero result, run-time error 209 (D1h) is generated. 

Also, while the OvrSeg parameter is passed to indicate which overlay should 
be loaded, a custom overlay error handler can operate by simply passing this 
parameter to the original overlay handler. 
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The first step in creating a custom overlay error handler is to declare two 
variables, thus: 


uses Overlay; 
var 
OrgOvrFunc: OvrReadFunc; 
EMS: boolean; 


The OrgOvrFunc variable is used to store the original overlay function address, 
so that the new error handler can call the original function for the actual task 
processing. 

Only two processes are likely to require error trapping: a disk read operation 
or, if EMS is used, an EMS read operation. Since only one of these will be error 
trapped, the EMS variable will show which operation is being guarded. So, after 
OvrInit is called, OvrRead Buf will hold the address of the default disk read function 
and can be copied to the OrgOvrFunc variable for storage: 


begin 
Ovrinitt "Example. OVR* 22 
OrgOvrFunc := OvrReadBuf; { save default } 


After the default process has been stored, the new CustomError handler’s 
address is transferred to the OvrReadBuf variable: 


OvrReadBuf := CustomError; { install new } 
EMS := False; 


The boolean variable, EMS, is set to False because, at this point, subsequent calls 
to read overlay files will be vectored to the custom error handler first, but, from 
these, will be passed to the disk read function. 

But what about EMS? If EMS is being used—or attempted—then OvrInitEMS 
should be the next overlay routine called: 


OvrInitEMsS;s 

if OvrResult = ovrOk then 

begin 

If the call to OvrInitEMS is successful, then the previously saved operation 
vector is no longer necessary, and the custom error handler needs to get a new 
assignment. Since the default EMS read function address is now in OvrReadBuf, 
the same process can be repeated: 


OvrReadBuf ; { save default } 
CustomError; { install new } 


OrgOvrFunc 
OvrReadBuf 
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EMS = True; 
end; 


The boolean variable EMS is set to True because, after this point, all calls to the 
default EMS function will be vectored to the custom error handler. 


end. 


The rest of the operations can continue as before, with the exception that either 
the EMS or disk operations initiated by the overlay handler will be vectored to the 
custom overlay handler. 


The Custom Overlay Handler 


For obvious reasons, the CustomError function has the same declaration and 
parameter list as the original functions it is replacing: 


function CustomError( OvrSeg: word ): integer; far; 
var 

Err: word; 
begin 


This function is explicitly declared to use far handling and declares a local 
variable Err to handle error codes. 
The custom handler begins by initiating a loop, which will exit only when the 


default operation returns a zero error code or, optionally, when an abort instruction 
from the user terminates further operations: 


repeat 
if not EMS then 


Before anything else is attempted, if EMS is false—meaning that this is still a 
disk read operation—any disk validation procedures desired, such as checking for 
a removable disk, will be installed. 

After any validation procedures are satisfied, the original parameter OvrSeg is 
passed on to the original function. Notice, particularly, that the custom handler has 
done exactly nothing with this parameter except to pass it along to the original 
process: 


Err := OrgOvrFunc( OvrSeg ); 


After calling the original process, the resulting error code—if any—is used to 
report the error to the user: 
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if Err <> QO then 
if EMS then ReportEMSError( Err ) 
else ReportDOSError( Err ); 


The Report___Error procedures are not shown, but for DOS errors, should 
expect error codes 3..6. For EMS errors, error codes will be in the range 80h..FFh 
and can be found in either Advanced MS-DOS Programming or MS-DOS Extensions, 
both by Ray Duncan. In general, however, for EMS, only errors 80h..85h are likely 
to be returned by overlay operations. 

The loop continues until Err is zero, indicating success: 


until Err 2& 2; 
CustomError := QO; 
end; 


For the calling process, CustomError must always return a zero error value, 
because any other value would be interpeted by the system as an error, interrupting 
program execution. 


Summary 


Turbo Pascal units provide a convenient means both for compiling libraries of 
subroutines to be used repeatedly by different applications, and for inclusion as 
overlay code to increase the amount of memory available for data and other 
processes. Compiling code as units, however, also requires a few special consider- 
ations in providing interface capabilities, as well as in using the optional initializa- 
tion facilities. 

Unlike the include files discussed in Chapter 16, overlays require far call 
handling, which is normally provided by using the {$F+} compiler directive. 

But there is one other option which wasn’t discussed previously: the Compiler 
Options menu shown in Figure 17-1—call Options /Compiler—provides two check 
box options in the Code generation block: Force far calls and Overlays allowed. 

The Force far calls option is the equivalent of the {$F+} compiler directive, while 
the Overlays allowed option is the equivalent of the {sO+} compiler directive. 

Thus, while compiling overlay units, both options can be checked, while only 
the far calls option needs to be checked during compliation of the program using 
the overlays. 

However, use of these two menu options is not recommended, for two reasons: 
First, the compiler options menu is easily overlooked when working with a series 
of programs or units, while the flag compiler directives are obvious and easily 
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spotted in the source code. Second, the far calls option can easily remain checked 
when it is not needed—i.e., when non-overlay programs are being compiled. While 
this latter error does not result in any serious defects, there is still a small difference 
in performance in using unnecessary far calls. 


Figure 17-1; Compiler Options for Units and Overlays 








Force far calls 
Overlays allowed 
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For most purposes, the information provided here on unit and overlay man- 
agement should be more than sufficient. If, however, you are using external 
procedure references, you may need to refer to the Turbo Pascal Programmer's Guide 
for additional information. 

Programs illustrating the topics covered in this chapter are listed below. Note 
that two references are made to include files that appear in Chapter 16 and are not 
repeated here. 
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{ses=sseeseeeeee qe 22e=5== 5 
{ READSCR2.PAS } 
{ demonstrates using } 
{ the PopUp unit } 
{ssxsee2eseeeeerssrzereeze} 


uses Crt, PopUp; 


var 
ts 3} % THtQ8Er2 
begin 
cirser: 


Gotorye 35. 722 
for } = 7 te 5 -do 
1or 1 £8 4 te -e0 do 
write(€ chr(€ random( 26 )+64 ) );3 
writeln( ‘The preceding five lines ', 
"were randomly written*’' ); 


{ read and copy five Lines from existing screen display } 


Check_Mode; 
gotioxyt 1, TQ 23 
writeln( 'The first five screen Lines are read as:' ); 
for ] += 1 6. 3.-a0 
for Tt = 1. te. -80 do 
write(€ Read_Screen( i, j ) ); 


readln; 
end. 
{HSHSSesSSSesSStSSSSSSSeescerestseeseaserrtessstsessa=zazz} 
{ Pop_Up.PAS } 
{ demonstrates converting an include file to a } 
{ unit source file to be used as an overlay } 
{maces eeSesseeresessesssese2esrseseracs=zsssssses=ess} 


unit Pop_Up; 

{$O+,F+} 

interface 

procedure Save_Screen( ScrNum: byte ); 


procedure Restore_Screen( ScrNum : byte ); 
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procedure Set_Color( Color: byte ); 
procedure Check_Mode; 
function Read_Screen( XPos, YPos : byte ): char; 
procedure Check_Kbd; 
implementation 
uses Urt; 
{$I POP_UP.INC } 
begin 
if LastMode <> Mono 


then ActiveScreen 
else ActiveScreen 


aColorScreen 
aMonoScreen; 


end. 
{x2=e8e8neseesneee2e2e2e22=) 
{ READSCR3.PAS } 
{ demonstrates using } 
COS overt eyo units. o.% 
{ssseeseseezecsestsesezese=} 
CSF +} 


uses Overlay, InitOvr, Crt, Pop_Up2, Frame; 


{$0 Pop_Up2} 
{$0 Frame} 


var 
1, J 32 edger: 
begin 
clrsecr; 
Box Windowl 1, 14: 40,210, ECTehtbive, Btue 7: 
for: 3.9m. 1:46 300: do writet -chrC renegom(26)+64 ) »; 
Box Windowt 41, 1, 6G; 10, LigntGeeeqn, DarkGray >; 
for: 7 -s2 4. to 300 do write chart: ceangom(26)4+64.). >: 
Window 13.17: 80, €2° 9% 
TextAttr := SOF; 
GOtONVS Tatts 
writeln(€ 'The above boxes were randomly created*' ); 
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{ read and copy ten Lines from existing screen display } 


csotoxyt 4, TS 2 
writeln(€ 'The top half of the screen is read as:' ); 
TOr {| 82 T to 18°00 
for 1 £2 1 ¢6 60 de 
write Read Screent 3, 3} 2 a: 


readln; 
end. 
{seeseeeeseeqessessesseeezez=} 
{ InitOvr.PAS } 
i Anette! “Goo tai tiatltize } 
{ the overlay handler } 
{s2esaeeesesastessesseezaz=} 


unit inrtovrs 


{$0O-,F+) { overlay not permitted, far calls forced } 
interface { interface section is empty } 
implementation { implementation section is empty 
uses Overlay; { initialization section initialzes } 
begin { the overlay handler and EMS } 
OvPintitt "“READSCRS.0VR" J: 
OvrInitEMS; 
end. 
{sssSeeSeSerSeSSeseeeesseseseecases===e=s=}) 
{ FRAME.PAS } 
{ creates frame unit for overlay } 
{See SS SS SSS SSS2SSSSSSS 58S e2eeeezze=}h 


unit Frame; 

{$O+,F+} 

interface 

procedure Box_Line( XAxis1, YAxis1, XAxis2, YAxis2 : byte ); 
procedure H_Line( XAxis1, YAxis, XAxis2 : byte ); 

procedure V_Line( XAxis, YAxis1, YAxise : byte ); 


procedure Box_Window( XAxis1, YAxis1, XAxis2, YAxis2, 
FcColor, BColor:e Byte 2; 
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procedure Center _cine¢  XAxie, YAxts, Limits: byte; 
CenterStr:' string): 

implementation 

uses Crt; 

{$I FRAME.INC} 

end. 
{Sess Sstecreesecesrcteste err sssseaseaetaeeenscesestecesess=) 
{ Pop_Up2.PAS } 
{ demonstrates converting an include file to a } 
{ unit source file to be used as an overlay } 
{SSHSSSSSsesSSsst Sse st eseeeststess testes eesssesesss2 = } 


unit Poo _Upze? 


{S$O+, Ft} 
interface 
procedure 


procedure 
procedure 
procedure 
function 


procedure 


Save_Screen( ScrNum: byte ); 


Restore_Screen( ScrNum 


set -Cotort: Cotor: byts:..22 


Check_Mode; 
Read _Screen( XPos, YPos 


Check_Kbd; 


implementation 


uses: Crt: 


C31 POP_UP. INC. > 


begin 


if LastMode = Mono 


then ActiveScreen 
else ActiveScreen 


end. 


py te: 35 


byte ): 


aMonoScreen 
aColorScreen; 


ener: 


{ 


ImAT Tat tzat ion .) 


Part 2 


Graphics Programming in Turbo Pascal 


There is a myth prevalent in the computer industry which holds that Pascal is not 
a graphics-oriented language and is not capable of graphics applications. Perhaps, 
in some past computer age, this myth may have been justified because there was a 
time when computers were not graphics-oriented (excepting the early Apple 
systems, which were graphics-oriented but not application-oriented), 

But yesterday’s myths are not today’s realities. Video systems have expanded 
greatly from the original CGA systems which were only vaguely graphics capable. 
And the early 2-MHz, 16K systems, which lacked both the speed and memory for 
graphics applications, are effectively obsolete, supplanted by 20/30+ MHz systems 
with megabyte and larger memories. 

At the same time, graphics interfaces and applications such as Microsoft 
Windows, OS/2, and Ventura Publisher are both popular and common. 

And, most importantly, Turbo Pascal has emerged as not only a graphics-ori- 
ented compiler, but, using the Borland Graphics Interface, as a graphics superstar. 
It provides the procedures and functions that support graphic applications and the 
speed of execution necessary to make graphic applications practical—as well as 
desirable. 

Graphics are no longer just elaborations used to fancily dress otherwise con- 
ventional programs or to provide color and imagery for arcade games. Instead, 
graphics have become not only a new standard, but a standard against which 
many—if not most—future applications will be judged. This is hardly a temporary 
trend. Even portable computers, though most still lack color capabilities, are 
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hurrying to match or emulate high-resolution graphics displays. My newest sys- 
tem, for example, has VGA video in the form of a back-lit, super-twist liquid crystal 
screen and, while color is emulated as 16 levels of gray, a total weight of 14 pounds, 
superb clarity, and go-anywhere operation are more than a fair trade-off. In fact, 
much of the typesetting and illustrations (both of which are impossible without 
excellent graphics capabilities) for this book have been executed ec guessed 
it—my lap top portable. 

When even portable computers can support great graphics, doesn’t it seem 
likely that graphics are here to stay? 


Chapter 18 


Introduction to Video Graphics 


While a program’s general appearance is an important factor, particularly in the 
competitive commercial environment, graphic displays have advantages far more 
important than the merely cosmetic. 

Today, the term Graphic User Interface, or GUI, is used as a generic reference 
for any application or system that employs graphic screen elements and mouse 
selection rather than relying solely on keyboard input controls. In general, GUI 
elements are designed for ready recognition without requiring explanations or 
documentation and provide for more human-oriented interactions than the famil- 
iar C:> prompt. In some cases, such as the aggressively icon-oriented Macintosh, 
this is taken to extremes which many find annoying. 

Extremes aside, a balanced combination of graphics and text elements permits 
the presentation of information in forms that are easily and rapidly understandable. 
For example, scrollbars that show location within long lists or page orientations 
and also provide both a mouse control for changing display position and mouse- 
operated pushbuttons (which change state to show selections), are marvelous 
graphic elements that operate without requiring explanation. 

In the same fashion, business graphs are often easier to understand and 
compare than columns of figures and, for many mathematical applications, a good 
three-dimensional graph reveals a whole world of understanding which raw data 
or formulas do not. For typesetting software, there is simply no substitute for 
graphics — witness the popular WordPerfect 5.0, which provides both the standard 
text displays and a graphics typeset view of a page output (including images). 
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On the other hand, elaborate folder and trashcan icons that must be dragged 
around the screen to accomplish anything at all can be an annoyance. Obviously, a 
balance is required. 

But, before worrying about what to use, the first requirement is simply to be 
able to create graphics displays. 


Which Graphics Display 


The current proliferation of video hardware (now including at least 10 standard 
video adapters) has presented its own problems for the programmer. Each design 
of video hardware supports a different set of capabilities, may use different memory 
addresses, may or may not support multiple graphics pages (and/or multiple text 
pages), and may support video modes ranging from 320x200 to 1024x768 pixel 
displays and ranging from monochrome to 256-color displays. 

Of course, the initial problem facing every graphics programmer is simply the 
question of identifying which video adapter is installed in what machine. One 
option has always been to ask end-users, allowing them to select the video mode 
that will be used. This is also a poor choice because even professional programmers 
are not always certain with what hardware they are working and the average 
end-user may not know if he or she has a graphics adapter at all, much less what 
type it is. The alternate choice is to have your software query the hardware to 
determine the present configuration. 

Assuming that some standard for hardware identification existed, this would 
be a simple matter. But, unfortunately for programmers, the proliferation of video 
adapter hardware has occurred without any formalized provisions for identifica- 
tion. In a previous book, Programming The IBM User Interface (Addison-Wesley, 
1988), I discussed several methods to test for the presence or absence of CGA/EGA 
video adapters and some of the problems inherent in correctly identifying hard- 
ware. 

Happily, the release of Turbo Pascal version 4.0 (and Turbo C 1.5) relieved most 
of the indecision of identifying, supporting, and using the various video adapter 
cards currently available. Also, judging by Borland’s past performance, it seems 
fairly safe to assume that new video adapters will be similarly supported. 

Unhappily, this welcome support for diverse video capabilities has resulted in 
creating its own confusion over how to use these new tools, what is possible and, 
in general, what to do with a plethora of new capabilities. 

This confusion is precisely the subject of this section. 
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Video Adapter Types 


Contemporary video cards range from the text-only original video systems to the 
ultra-high resolution IBM-8514 (popular with typesetting and CAD software appli- 
cations), with a variety of resolutions lying between the two. The higher resolution 
video cards must be matched with monitors of corresponding pixel resolution, but 
this is a hardware matter and, for all practical purposes as a programmer, you may 
simply assume the hardware present corresponds to the identification returned by 
Turbo Pascal’s DetectGraph function. Any discrepancies in matching between 
video cards and monitors are the end-user’s responsibility and should not be the 
programmer’s concern. 

Most, if not all, multisync and higher resolution graphics video cards offer some 
recognition of the actual monitor type. 


Video Modes 


Every PC, XT, or AT is equipped with some type of video adapter card. Beginning 
with the very basic video card, you may have the Monochrome Display Adapter 
(MDA), which supports text-only display. If this is the case, you will not be able to 
program or use graphics without upgrading your system. 

The first step up is the popular Color Graphics Adapter (CGA) card, while 
higher resolutions and wider options are provided by the Hercules Monochrome 
Graphics Adapters, Multi Color Graphics Array (MCGA), and Enhanced Graphics 
Adapter (EGA) video adapters. For more advanced graphics capabilities, as for 
typesetting or CAD applications, the AT&T 400-Line Graphic Adapter, Variable or 
Video Graphics Array (VGA), sometimes called Multi-Sync video, PC-3270, and 
IBM-8514 video adapters all offer even higher pixel resolutions. 

In Turbo Pascal, graphics support for all of these types is provided in the form 
of six graphics interface (.BGI) units (ATT, CGA, EGAVGA, HERC, IBM8514, and 
PC3270) and four graphics fonts (GOTH.CHR, LITT.CHR, SANS.CHR, and 
TRIP.CHR). As new video graphics cards appear, new .BGI units may be included 
for support—while new .CHR fonts may be user-created or purchased from com- 
mercial sources. 

The graphics support units, however, are not included in the standard memory 
models as distributed—an omission made for the express purpose of speeding 
compilation time when graphics are not needed. 
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Disadvantages 


Once a program has been compiled the .EXE program can be distributed with 
external .BGI and .CHR files required for operation. Together, these files require 
approximately 60K of disk space. Granted, this isn’t an excessive requirement in 
terms of storage, but relying on external files for execution can create difficulties. 

First, a call to InitGraph must include the drive and path specification of where 
the .BGI (and .CHR) modules are located. If no path is specified, then the current 
directory is assumed. Normally, this routing information is supplied by the pro- 
grammer and, if the required files are not found (a problem which can occur for a 
variety of reasons no matter how well designed a program is), your program will 
terminate! 

Second, if the default (current) path is assumed and all external files are present 
but the program is called from another directory or drive, this will also cause a 
crash! 

Third, never depend on the end-user to be aware of the importance of external 
files. They may love your program and guard it jealously but, as soon as space 
becomes a problem, may erase necessary external files. It happens, be prepared. 
Alternatively, you can link the ._BGI and .CHR files directly into the graphics library, 
increasing your .EXE program in size by about 30K, while making the drivers and 
fonts a part of your .EXE program rather than external files (see Chapter 24, 
Advanced Graphics Pascal). 


The GRAPH Unit 


The Graph.TPU unit contains a comprehensive library of constants, procedures and 
functions for graphic operations, ranging from high-level calls such as Set ViewPort 
and Circle to bit-oriented operations such as GetImage and PutImage as well as 
colors, palettes, sizable stroked fonts and line and fill styles. 

Because all of the programs in this section will be graphics-oriented, the Graph 
unit will be included in all uses statements as: 


uses GRAPH; 


When functions from several units are required, multiple units can be refer- 
enced in a single line, thus: 


uses CRT, DOS, GRAPH; 
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Knock, Knock! What’s There? 


The first step in your graphics program is to initialize the appropriate graphics 
driver. For a list of supported graphics video cards, drivers, and graphics modes, 
see Table 18-1. 


Table 18-1: Video Modes Supported by Turbo Pascal 


Graphics Graphics Column Palette? Video 
Driver ' Value Modes * Value X Row OrColors Pages 
DETECT 0 Requests InitGraph to execute autodetection 
CGA 1 CGACO0 0 320x200 CO 1 
CGACI1 1 320x200 Cl 1 
CGAC2 2 320x200 C2 1 
CGAC3 3 320x200 C3 1 
CGAHI | 640x200 2colors 1 
MCGA 2 MCGACO 0 320x200 CO 1 
MCGAC1 1 320x200°.. Cl 1 
MCGAC2 2 320x200 C2 1 
MCGAC3 3 320x200 C3 1 
MCGAMED 4 640x200 2colors 1 
MCGAHI 5 640x480 2colors 1 
EGA 3 EGALO 0 640x200 16colors 4 
EGAHI 1 640x350 16colors 2 
EGA64 4 EGA64LO 0 640x200 1l6colors 1 
EGA64HI 1 640x350 4colors 1 
EGAMONO 5 EGAMONOHI 3 640x350 2colors 1-2" 
IBM8514” 6 IBM8514LO— OO 640x480 256 colors 1 
IBM8514HI 1 1024x768 256colors 1 
HERC 7 HERCMONOHI 0 720x348 2colors 4 
ATT400 8 ATT400C0 0 320x200 CO 1 
ATT400C1 1 320x200 Cl 1 
ATT400C2 2 320x200 . C2 1 
ATT400C3 3 320x200 C3 1 
ATT400MED 1 640x200 2colors 1 
ATT400HI 5 640x200 2colors 1 
VGA 9 VGALO 0 640x200 16colors 4 
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Table 18-1: Video Modes Supported by Turbo Pascal (Continued) 


Graphics Graphics Column Palette’ Video 

Driver ! Value Modes ° Value X Row or Colors Pages 
VGAMED 1 640x350 1l6colors 2 
VGAHI 2 640x480 lécolors 1 

PC3270 10 PC3270HI 0 720x350) . 2: colors 1 


1. The GraphicDriver and GraphicMode names are constants defined in the GRAPH unit, as are the 
corresponding numerical and mode values (see note 2). 


2. Mode settings returned by InitGraph, DetectGraph, or GetGraphMode. 
3. CO..C3 refer to the predefined 4-color palettes—see SetPalette. 


4, With 64K on an EGAMONO card, only one video page is supported; with 256K, two video pages 
are supported. 


5. Autodetection will not correctly recognize the IBM-8514 graphics card. Instead, InitGraph or 
DetectGraph will identify the IBM-8514 card as a VGA graphics card which the IBM-8514 will 
emulate correctly (IBM8514LO is equivalent to VGAHID). To use the higher resolution mode 
(IBM8514HI, which is 1024x768 pixels), assign the value IBM8514 (numerical value 6-—defined in 
GRAPH) to the graphdriver variable before calling InitGraph. Do not use DetectGraph or DETECT 
with InitGraph. See also the text notes on IBM-8514 and SetRBGPalette. 


DetectGraph Procedure Graph 


Normally, the DetectGraph procedure is called by InitGraph, but it can also be 
called independently in order to determine the current graphics driver and graph- 
ics mode. 


Declaration: DetectGraph( var GraphDriver, GraphMode: integer ); 
Example: 
uses GRAPH; 
var 
GraphDriver, GraphMode: integer; 
begin 
GraphDriver := DETECT; 
DetectGraph( GraphDriver, GraphMode ); 


end; 


If a problem occurs, GraphDriver returns an error code; otherwise, Graph- 
Driver identifies the appropriate driver type and GraphMode returns the highest 
valid video mode for this driver. For DetectGraph, no driver path is required (see 
InitGraph). 
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The DetectGraph function does not initialize any graphics settings. The princi- 
pal reason for calling DetectGraph directly would be to subsequently use InitGraph 
to calla specific graphics driver or to select a graphics mode which InitGraph would 
not call by default. Alternatively, a different mode can be called after initialization 
by using the SetGraphMode function. 

GraphDriver returns a driver type or error code; GraphMode returns the 
highest valid video mode. 


InitGraph ~=Procedure Graph 


The InitGraph procedure sets the initial graphics parameter values, loads the 
proper graphics driver, and sets the system to the desired graphics mode. 


Declaration: InitGraph( var GraphDriver: integer; 
var GraphMode: integer; DriverPath: string ); 


Example: 
uses GRAPH; 
const 
DriverPath = ''; 
var 
GraphDriver, GraphMode : integer; 


begin 
GraphDriver :;= DETECT; 
InitGraph( GraphDriver, GraphMode, DriverPath ); 


end. 


Setting GraphDriver as zero (DETECT) instructs InitGraph to call Detect- 
Graph(GraphDriver, GraphMode) to determine the type (and settings) of the 
installed video graphics adapter. If an error occurs, GraphDriver returns an error 
code indicating the type of error. Table 18-2 lists the graphic error codes. 

The DetectGraph and GraphResult functions return the same error codes as 
shown in Table 18-2. If no error occurs, then the internal error code is set to zero 
and InitGraph allocates memory for the appropriate graphics driver, loads the 
required .BGI file from disk, and sets the default graphics parameter values. Also, 
GraphDriver returns the driver type while GraphMode returns the mode setting. 
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Table 18-2: Initialization Graphic Error Codes 
Code Message 


—2 Cannot detect graphics card 

—3 Cannot locate graphics driver file(s) 

—4 Invalid driver (or not recognized) 

—5 Insufficient memory to load graphics driver 


GraphDriver and GraphMode can also be specified (either by using the appro- 
priate numerical constants or by using the driver and mode names as defined in 
the GRAPH.TPU unit). In either case, DriverPath shows the drive and path where 
the .BGI graphics drivers are located. If DriverPath is null then these files must be 
located in the default directory. If they are located in a different directory, then the 
complete path specification should be shown as: 


DriverPath = '\TP\BGI'; 


Since the DriverPath set by InitGraph is also used by SetTextStyle to search for 
the character font (.CHR) files, both .BGI and .CHR files must be located in the same 
directory. 

GraphDriver returns a driver type or error code; GraphMode returns the 
highest valid video mode. 


GetDriverName Function Graph 
GetDriverName returns a string with the name of the current graphics driver. 


Declaration: GetDriverName: string; 


Example: 
uses GRAPH; 


OutTextXY(€ 50, 50, ‘Using driver ' + GetDriverName ); 


GetDriverName can only be used after InitGraph has established a graphics 
driver and mode. See GetModeName for related information. 


Graphics Error Functions 


As mentioned, if a graphics video card is not present, if the graphics drivers are not 
found, or if some other error occurs during the detection of initialization, an error 
code is returned by DetectGraph or InitGraph. There are, however, other conditions 
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where a graphics error can occur and the functions GraphResult and GraphError- 
Msg are provided to test and display appropriate error results and messages. 


GraphResult Function Graph 


The GraphResult function returns a numerical error code set by the last graphics 
operation reporting an error. This will be an integer value in the range —14..0. Since 
the error condition is reset to zero when GraphResult is called, the returned value 
should be stored in a local variable and then tested for further action. 


Declaration: GraphResult: integer 


Example: 
uses GRAPH; 
var 
ErrorNumber: integer; 


ErrorNumber := GraphResult; 


GraphResult returns an error code (—14..0), see Table 18-3 for interpretation. 


Table 18-3: Graphics Error Messages 





Error Graphic Error 
Code Constant Error Message String 
0 grOk No error 
-1 grNolInitGraph .BGI graphics not installed (use InitGraph) 
—2 grNotDetected Graphics hardware not detected 
—3 grFileNotFound Device driver file not found (.BGI file) 
—4 grInvalidDriver Invalid device driver file 
—5 grNoLoadMem Not enough memory to load driver 
—6 grNoScanMem Out of memory in scan fill 
—7 grNoFloodMem Out of memory in flood fill 
—8 grFontNotFound Font file not found (.CHR file) 
-9 grNoFontMem Not enough memory to load font 
-10 grInvalidMode Invalid graphics mode for selected driver 
-11 grError Graphics error (generic error) 
-12 grlOerror Graphics I/O error 
-13 erInvalidFont Invalid font file 
—14 grinvalidFontNum — Invalid font number 


The GraphicsErrors constants and error messages are defined in the GRAPH 
unit. 
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GraphErrorMsg Function Graph 


The GraphErrorMsg function returns a pointer to the appropriate error message 
string. These strings are defined in the graphics library but a separate error message 
routine can be created to display a more complete or more informative error 
message if desired. 


Declaration: GraphErrorMsg( ErrorCode: integer ): string 
Example: 
uses GRAPH; 
var 
ErrorNumber: integer; 


ErrorNumber = GraphResult; 
writeln(€ GraphErrorMsg( ErrorNumber ) ); 


Other Graphics Mode Functions 


With the exceptions of the EGAMONO, HERC, and PC3270 video drivers, each 
video driver supports two or more video modes that offer varying pixel resolutions 
or different color palettes. To handle mode inquiries and to change operating 
modes, Turbo Pascal provides several functions: 


GetGraphMode Function Graph 


The GetGraphMode function returns an integer value showing the current (oper- 
ational) graphics mode set by InitGraph or SetGraphMode. 


Declaration: GetGraphMode: integer; 
Example: 
uses Graph; 
var 
CurrentMode : integer; 


CurrentMode = GetGraphMode; 


GetModeRange Procedure Graph 


The GetModeRange function is called with an integer value specifying the graphics 
driver (which may be an integer variable or one of the constants defined in the 
GRAPH unit) and returns two values defining the minimum and maximum valid 
modes supported by the indicated driver. 
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Declaration: GetModeRange( GraphDriver: integer; 
var LoMode, HiMode: integer ); 

Example: 

uses Graph; 


var 
LoMode, HiMode : integer; 


GetModeRange( GraphDriver, LoMode, HiMode ); 


If the value passed as GraphDriver is invalid, then both LoMode and HiMode 
return —1. 


GetMaxMode Function Graph 


The GetMaxMode function returns the highest mode number valid for the currently 
loaded driver, returning the value directly from the driver. The GetModeRange 
function is still supported but is valid for the BGI (Borland-supplied) drivers only. 


Declaration: GetMaxMode: word; 


Example: 
uses Graph; 
var 
MaxMode : integer; 


MaxMode := GetMaxMode; 


All drivers support modes 0..GetMaxModes and the value returned is the 
maximum value that can be passed to the SetGraphMode procedure. 


GetModeName Function Graph 


The GetModeName function is called with a mode value and returns the appropri- 
ate mode name for the current graphics driver. 


Declaration: GetModeName( Mode: integer ): string 
Example: 
uses Graph; 


var 
1 : tategers 


OutTextXY¢€. 50, 50, ‘Valid modes ares... 2: 
for i := 0 to GetMaxMode do 
OutTextxY¢ 60, 65 + 10° * 4; “@ethodeName( 7 2) 23 
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Mode names are embedded in each graphics driver and can be used as menus, 
to display status, or to report system capabilities. 


GraphDefaults Procedure Graph 


The GraphDefaults procedure resets all graphic settings to their default values (the 
values originally set by InitGraph and defined in the Graph unit). This includes 
resetting the viewport (graphics window) to the entire screen; moving the current 
position to (0,0); resetting default palette colors, background color, and drawing 
color; resetting the default file and pattern styles; and resetting the default text font 
and justification modes. 


Declaration: GraphDefaults; 
Example: 
uses Graph; 


GraphDefaults; 


SetGraphMode Procedure Graph 


The graphics mode must have been previously initialized by InitGraph. The 
SetGraphMode function must be called with a graphics mode that is valid for the 
current device driver (use GetGraphMode to find the current mode value or 
GetModeRange to check permissible values). When called, SetGraphMode selects 
a new graphics mode, clearing the screen and resetting all graphics variables to 
their default values (see GraphDefaults). 


Declaration: SetGraphMode( Mode: integer ); 
Example: 
uses Graph; 
var 
ModeNumber : integer; 


SetGraphMode( ModeNumber ); 


The SetGraphMode function can also be used with the RestoreCrt function to 
switch back and forth between text and graphics displays. InitGraph must have 
been called before either of these functions can be used. 


Example: 
uses Graph; 
var 
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CurrentMode : integer; 


CurrentMode = GetGraphMode; 
RestoreCrtMode; { text mode } 
SetGraphMode( CurrentMode ); { graphics mode } 
If SetGraphMode is called with a value that is invalid for the current device 

driver, GraphResult will return a value of —10 (grInvalidMode). 


RestoreCrtMode Procedure Graph 


The RestoreCrtMode procedure resets the system video to the original text mode 
detected by the call to InitGraph. This can be used with SetGraphMode to alternate 
between text and graphics displays. 


Declaration: RestoreCrtMode; 


Example: 
uses Graph; 


RestoreCrtMode; 


CloseGraph Procedure Graph 


The CloseGraph procedure restores the system to the normal text mode originally 
detected by InitGraph. This also deallocates the memory used by the graphics 
system for drivers, fonts, and internal buffer. 


Declaration: CloseGraph; 


Example: 
uses Graph; 


CloseGraph; 


If you wish to switch back and forth between text and graphics, use the 
RestoreCrtMode and SetGraphMode functions. 


{ssSEeeeee2teeererersssessesezs2e2see2- } 
{ FIRSTGRP.PAS } 
{ demo for initializing graphics } 
{ mode in Turbo Pascal version 6.0 1} 
{SeseSse2eSeSSS2Sesrceceastssesscktesasceees =) 


uses Graph, Crt; 


type 
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const 
Fonts 2: errayt O2:46 2-0Ff Steta: = 
CPi ete bes Tree | USWA st Yo rSeaneSerst!, 
sh oa Oe ik a 
LineStyvee ? arrayl. O..4¢: 2 ot 'str20-s 
C\'$etia*t,. "Dotted", "Center; *dashed's 
‘ser Defined". 3 
PILLS tyvi es -s errayt: Gaiwtt: 2 oF: &tre0.= 
C PEMD tyY’ ss Satie’, “tine Pitt, *Lignt- Staeeh*, 
be vesn', "Back Blhaéh’? 5: 'Wiagnt Back: Stech", 
Hetcn’ ..  whaten’ >: “Later leave’: ‘Wide dot’, 
‘tiose pot’ 2; 
Textbirect +: arrnayl: 0,070 Jef: iStritg. = 
Cc  Wort-zontal’; "Vertical? 33 
HortzJeet +  arraye: O.:.4):1. aT: Streg: = 
CPF pen Lert’; 'fentered' | Fl usn Right! 2: 
VertJdust << arteyt 0..2 2 of. 'Strig: = 
CC *B0t ton," Centereqs 2 Top: Ds 


var 
GraphDriver, 
GraphMode, 
AspectRatio, 
MaxX, MaxyY, 
MaxColors .canteser: 
Xasp, yasp 3s: word: 
Palette : Palettetype; 


graphics driver value 
graphics mode value 
screen pixel aspect ratio 
maximum screen resolution 
maximum colors available 
factors for aspect ratio 


EA OR 


functton Nest: Val, Digit : Anteger: J: string? 

var { converts integer to string 
Butter 2 string: 

begin 
Str Netepigqit, Burrer. ds 
N2S := Buffer; 

end; 


funct ton RESt. Val ss real? Bigit, Decimal: .integer ): string; 
var { converts real to string 
Buffer : string; 
begin 
etrt: Vat: Digit: Decimal, Butter); 
R2S := Buffer; 
end; 


Wwe YY Ye 


procedure TestGraphicError; 
var 

ErrorCode 
begin 


integer; 
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ErrorCode := GraphResult; { check the result } 
if ErrorCode <> grOk then t if an - ertor oecurs } 
begin { reset to text mode } 
CloseGraph; { report the error } 
writeln(€' Graphics System Error: ', 
GraphErrorMsg( ErrorCode ) ); 
halt€ 1 ); { and halt program } 
end; 
end; 
procedure ChangeTextStyle( Fnt, Dir, ChrSz integer ); 
var 
ErrorCode integer; 
begin 
ErrorCode := GraphResult; { clear error code } 
setTextStyiet.Fnt, Bit; Chrsz 2: 
TestGraphicError; Cceneck tor errors } 
end; 
procedure StatusLine( msg tring 2: 
var { display status Line at bottom } 
Height integer; 
begin 
SetViewPort( 0, O, MaxX, MaxY, True ); 
SetColor( MaxColors=-1 ); { start with max color } 
ChangeTextStyle(€ DefaultFont, HorizDir, 1 ); 
SetTextJustify( CentérText, TopText ); 
SetLineStyle(€ Solidin, 0O,.NormWidth ); 
SOECPILLStytet EmntyFritti, 8-23 
Height := TextHeight( msg ); { get char height } 
Bar€ O, MaxY-CHeight+4), MaxX, MaxY ); 
Rectangle( O, MaxY-CHeight+4), MaxX, MaxY ); 
OutTextXY( MaxX div 2, MaxY-CHeight+#+2), msg ); 
SetViewPort( 1, Height+5, 
MaxX-1, MaxY-CHeight+5), True ); 
end; 
procedure DrawBorder; 
var { draw solid Line around current viewport } 
vp ViewPortType; 
begin 
setCotort MaxCcolors = “1.2% <'set draw color } 
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SetLineStyle( SolidLn, 0, NormWidth ); 

GetViewSettings( vp ); 

RectandteC 0,0, VPs xe-vp.xl, VP. yervpi yt) 3 
end; 


procedure ReportWindow( header : string ); 


var 
Height : integer; 
begin 
ClearDevice; { clear graphics screen } 


SetColor( MaxColors - 1 ); 
SetViewPort( 0, O, MaxX, MaxY, True ); 
Height := TextHeight( header ); { char height } 
ChangeTextStyle( DefaultFont, HorizDir, 1 ); 
SetTextJustify( CenterText, TopText ); 
Out TextxyY( Maxx div 2,2, header); 
SetViewPort( O, Height+4, 

MaxX, MaxY-CHeight+4), True ); 
DrawBorder; 
SetViewPort( 1, Height+t5, 

MaxX-1, MaxY-CHeight+5), True ); 

end; 


procedure Pause; 


var 
Ch -t) Crary: 
begin 
Stetustinet. 'Press any: Key. 6st. 23 { put msg on screen } 
while KeyPressed do Ch := ReadKey; 
Ch := ReadKey; { wait for a key entry } 
ClearDevice; { clear the screen } 
end; 


procedure StepDisplay( var y : integer ); 


var { steps display & color } 
Color :.-tateger; 
begin 
Inet. -¥,--FextHetantt -*W! .2 #235 
Cotor 25: GetColor:=.13 
if Color =:'0 then Color := GetMaxColor; 
SetCotort Color. 23 
end; 


procedure ReportStatus; 
var { report current system configuration } 
ViewInfo : ViewPorttype; 
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LineInfo : LineSettingstype; 
FtlLlinte : FILtSettingstype; 
TextInfo : TextSettingstype; 
Driver, Mode, Buffer : string; 
X> ¥; Graephht, GrapnLo :-integer; 
begin 
x £= 10; y 22-283 
ReportWindow( ‘Graphic Status Report' ); 
GetViewSettings( ViewInfo ); 
GetLineSettings( LineInfo ); 
GetFillSettings( FillInfo ); 
GetTextSettings( TextInfo ); 
GetPalette( Palette ); 
SetTextJustify( LeftText, TopText ); 
OutTextXY( x, y, ‘Graphics driver rs REN 
GetDriverName + '.BGI'); 
StepDisplay( y ); 
OutTextxXY( x, y, ‘Graphics device gn Se 


N2S€ (GraphdOriver,; 12+ ' ) ° + 
GetDriverName ); 
StepDdDisplayliy* 2); ? 
OutTextXY( x, y, 'Graphics mode ¢ €{ ) & 
N2S¢€ GraphMode, 1) + ° ) ' +4 
GetModeName( GraphMode ) ); 
StepDisplay( y ); 
GetModeRange( GraphDriver, GraphHi, GraphLo ); 
OutTextXY( x, y, 'Valid mode range | Roy. 2. ''.+ 
N2S¢C- Graphti,;: + 2.%>.%, tien = * + 
N2S¢: Graphlo, “4:2 2; 
StepDisplay( y ); 
OutTextxY¥( x, ye S$ereen resolution a 
i RSI: © Ie itaness = Seas crear. 
NeSt GOtRaxts e262 9! , -' + 
NZSC GetmaxY, e:2°>*e * 2" OF 
StepDisplay( y ); 
OutTextxY( x, y, ‘Current viewport - € Fem 
N2SC ViewInfo.x1T, 2@ 2 oi beet 
NZSO¢ ViewIntoc¥te: 27 cer 
N2SC ViewInto.*2;5-:227-%:7 5" + 
NZS. Venn fos te, 3253 eta Og 
StepDisplay( y ); 
if Viewlnfo.~€lip;then: B8effer: :=.* ON’ 
else Buffer :=-*OFF'; 
Out Texthyt:-%, ¥e 'ClTepinag eM 


Buffer ); 
StepDisplay( y ); 
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OuUtFexerzyt x, .¥, PEuUrfrant nosteten: (CP? 230.) se 
Reet Getk) 2 Rohe, ot le 
NESE GOtyl 5 ake fe Me Re 

StepDisplay( y ); 

OCOutTtextryG 2, y¥>. Rex (cotoons this: cotar? 3’ 
Nese Maextolora;, 20): + ¢°- 7 
N2S<t GetCotor, 2:30:33 


aa 
Wee a 


StepDisplay( y ); 
Out TOeRCRG Xo ¥,. MAIS CAT Ck FE etre Ee eels 
N2St Linelnie., Te ciné@es, 2) 4+-' 
LineStyleslC LineInfo.LineStyle J] ); 
StepDisplay( y ); 
OUCTORERT(. ay Vy, PETA. color 7) setts eet ea, 
NERC FTEEING SG eter) (2.6340 ' oF he 
FillStyles€ FilliInfo.Pattern J ); 
StepDisplay( y ); 
OutTextxy< x, vy, *Cheracter:si26 7 tont , 
N2SC TextInfo.CharSize, 2 
FORtSC  Textinvtoe. Font: i >: 


of 

pee Toh ee 

StepDisplay( y ); 

Out TextrzyT(: -&,: ¥y%  * text direction SE ae 
TextDirectlC TextInfo.Direction J] ); 

StepDisplay( y ); 

QUSTeRERTS Ks ¥> FHS PESHtSet Teer ity ae ele 
Hart2iJusttl  Texeinio. dort2 2°93 

StepDisplay( y ); 

Out Textxzyei xecy,:* Vert Teet <jueeity By Ot oe 
VertJustti TExtinfo.vert 1); 

StepDisplay( y ); 

Out TOKCAT CC Kes CC ASROCT atte exe eh Ss 


NZ2SOC URES, 402 He Oe 
Nest Vaso) 412 ete 
Reet ABDOEERSTIOG, 35 °S (Dod? 
Pause; 
end; 
procedure Initialize; 
begin { initialize graphics system and report errors 
GraphDriver := DETECT; { Request auto-detection 
InitGraph(€ GraphDriver, GraphMode, '\TP\BGI' ); 
TestGraphicError; { check graphics errors 
GetPalette( Palette ); { read palette parameters 
MaxColors := GetMaxColor + 1; 
MaxX := 380; { set viewport size 


MaxyY: 2-194; 
GetAspectRatio(€ xasp, yasp ); { hardware aspect 
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AspectRatio := xasp div yasp; 


end; { calculate aspect ratio } 
begin 
Initialize; { set graphics mode } 
ReportStatus; { show graphics settings } 
CloseGraph; { set text mode 


end. 
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Chapter 19 


Viewport, Screen, and Page Functions 


Just as windowing and screen management routines are provided for text display 
modes, similar control features are provided for graphics display modes. These 
include the ClearDevice and ClearViewPort functions (graphics equivalents of 
ClrScr), SetViewPort (equivalent to Window), GetViewSettings, and the SetActive- 
Page and SetVisualPage functions. 

Not all of these graphics functions have text mode equivalents and there are 
several text mode functions that are not provided with graphics mode equivalents. 
Even when a graphics function appears similar to the text mode equivalent, it may 
not operate identically to the text function. 

The first of these screen management functions is ClearDevice. 


ClearDevice Procedure Graph 


The ClearDevice function erases the entire graphics screen—regardless of viewport 
settings—and moves the current position (CP) to the screen home position (0,0). 
This does not affect the active viewport (if any is in effect). The viewport settings 
remain unchanged, but the entire screen is cleared, not merely the viewport. No 
values are returned and no error condition should be generated. 


Declaration: ClearDevice; 


Example: 
uses GRAPH; 


ClearDevice; 
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While ClearDevice is similar to the text command ClrScr, where the text 
function is window sensitive (it can be used to clear only the currently active 
window), the ClearDevice command resets the entire active graphics screen but 
does not affect alternate graphics screens (if any are supported by the graphics 
hardware present). Remember that text functions such as ClrScr do not work in 
graphics modes and vice versa. See ClearViewPort, SetActivePage, and SetVisual- 
Page for more information. 


ClearViewPort Procedure Graph 


The ClearViewPort procedure erases the current viewport (graphics window), 
moving the current position (CP) to home (0,0) within the viewport setting. Unlike 
the ClearDevice function, ClearViewPort is limited to a specific area of the screen 
and operates similarly to the text command ClrScr with an active window setting. 


Declaration: ClearViewPort; 
Example: 
uses GRAPH; 


ClearViewPort; 


See also GetViewSettings and SetViewPort. 


SetViewPort Procedure Graph 


The SetViewPort procedure is roughly equivalent to the text procedure Window 
and is used to set an active viewport. The coordinates XLeft, YTop, XRight, and 
YBottom are absolute screen coordinates and affect only the active graphics page 
(see SetActivePage). 


Declaration: SetViewPort( X1, Y1, X2, Y2: integer; Clip: boolean ); 
Example: 
uses GRAPH; 
var 
XLett;. YTop, XRight, YBottom <: integer; 
ClipFlag : boolean; 


SetViewPort( XLeft, YTop, XRight, YBottom, 
Clipflia@g 92 


The fifth argument passed to SetViewPort is the ClipFlag. If ClipFlag is true, 
clipping will be in effect and all drawings will be restricted to the current viewport. 
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If ClipFlag is false, then drawings may extend beyond the viewport perimeters 
without limitation. 

Please note that the viewport limits do not affect the GetImage or PutImage 
commands and a pixel image being written to the screen will not be truncated at 
the viewport perimeter, regardless of the ClipFlag setting. 

If invalid coordinates are passed to SetViewPort, GraphResult will return a 
value of —-11 (graphics error or generic error) and the previous viewport settings (if 
any) will remain in effect. Both the InitGraph and SetGraphMode functions initial- 
ize the current viewport to the entire graphics screen as defined by the current mode 
setting. See also ClearViewPort and GetViewSettings. 


GetViewSettings Procedure Graph 


The GetViewSettings procedure uses the record variable ViewPort to return the 
current graphics window coordinates and the ClipFlag setting. The coordinates 
returned are absolute screen coordinates. 


Declaration: GetViewSettings( var ViewPort: ViewPortType ); 


Example: 
uses Graph; 
var 
ViewPort : ViewPortType; 


GetViewSettings( ViewPort ); 


If ClipFlag is true, drawings are truncated at the current viewport margins. See 
SetViewPort for further details. See also ClearViewPort, InitGraph, and SetGraph- 
Mode. 

The ViewPortType record structure is predefined (in the Graph unit) as: 


type 
ViewPortType = record 
KTS ¥Tp Reo Vers integers 
clip : boolean; 
end; 
Multiple Graphics Pages 


Several graphics video cards offer support for two to four pages of graphics display 
(most without restricting color or resolution). To allow use of these capabilities, 
Turbo Pascal provides two procedures: SetActivePage, which selects the active 
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graphics output page and SetVisualPage, which selects the graphics page that 
actually appears on the screen (monitor). 

These are most often used for graphics animation. These commands are valid 
only with the drivers and modes shown in Table 19-1: 


Table 19-1: Graphics Modes Supporting Multiple Pages 


Graphics Driver — Graphics Mode Column Colors Graphics 
driver Value Mode(s) Value X Row Available Pages 
EGA 3 EGALO 0 640x200 1l6colors 4 
EGAHI 1 640x350 16colors 2 
EGAMONO a EGA-MONOHI 3 640x350 2colors 4! 
HERC Y HERC-MONOHI 0 720x348 2colors 2 
VGA ¥ VGALO 0 640x200 16colors 4 
VGAMED 1 640x350 16colors 27 


1. The EGAMono card must have 256K RAM to support multiple video pages—some EGAMono 
cards have only 64K RAM. 


2. Originally, the VGAHI mode (640x480) supported only one graphics page, but many VGA-capa- 
ble video cards (i.e., multi-sync cards) support two to four pages. No standards to determine page 
support capabilities currently exist. 


Remember, where multiple graphics pages are supported, the graphics pages 
are numbered from zero and page zero is active by default. 

Where multiple graphics pages are not supported, the SetActivePage and 
SetVisualPage commands will simply not operate. By default, page zero will remain 
as the active output page and the active visual page. 

But, relying on this default behavior is not necessarily the best approach to 
handling multiple video pages. In many cases, it might be better to know how 
many—if any— video pages are available and have your program respond accord- 
ingly. The following sample procedure, VideoPages, returns zero if no alternate 
video pages are available or an integer value if more than one video page is 
supported: 


uses Graph; 


var 
GraphDriver, GraphMode : integer; 


function VideoPages : integer; 
var 
Result : integer; 
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begin 
Result := 0; 
case GraphDriver of 
EGA : case GetGraphMode of 


EGALO : Result := 3; 
EGAHI : Result := 1; 
end; { case } 
EGAMONO : Result := O; 

HERC =: Result := 1; 

VGA : case GetGraphMode o 
VGALO s Result <= 3; 
VGAMED : Result := 1; 
VGAHI : Result := QO; 


end; { case } 
end; { case } 
VideoPages := Result; 
end; 


Some EGAMono cards support four video pages, but mode and driver settings 
do not identify which cards have 256K RAM and which have only 64K RAM. Thus, 
the best default value returned is 0, however, this can be changed if your application 
requires a different response. 

All remaining drivers and modes identify themselves as supporting single 
video pages, but newer video cards may require modification of this selection table. 
As mentioned previously, no standards for determining the number of supported 
video pages exist. 


SetActivePage 


The SetActivePage function selects which graphics page (PageNum) will be used 
for output by all graphics functions. This does not affect the graphics page currently 
being displayed (see SetVisualPage), but does allow graphics operations to be 
directed to an invisible page. It is then displayed either by using the GetImage or 
the PutImage function (use the PutImage function after changing the active page 
to match the visual page) or by changing the displayed page. 


Declaration: SetActivePage( Page: word ); 
Example: 
uses GRAPH; 
var 
PageNum : word; 


SetActivePage( PageNum ); 
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SetVisualPage 


The SetVisualPage function selects the specified graphics page (PageNum) for 
active display. This is not necessarily the same as the active output graphics page 
(see SetActivePage) but it is used to switch the video display between different 
graphics pages. The change is effective immediately (certainly too fast for the eye 
to follow), requiring only one screen refresh cycle for a complete display change. 


Declaration: SetVisualPage( Page: word ); 
Example: 
uses GRAPH; 
var 
PageNum : integer; 


SetVisualPage( PageNum ); 


Chapter 20 


Color and Palette Functions 


In addition to knowing which graphics card and which graphics driver to use, you 
also need to know what palettes or colors are supported. 

With the CGA, MCGA, and ATT400 drivers in 320x200 pixel modes, color 
selections are limited to the four-color predefined color palettes (CO, C1, C2, and 
C3). With higher resolutions, some graphics cards offer 16 colors; others offer two 
or four colors, but with color selection independent of the predefined palettes. 

Lastly, with the IBM8514, a palette of 256 colors becomes possible with a tint 
selection from a total of 262,144 (40000h) shades. The following color and palette 
functions are not compatible with the IBM8514 driver—see IBM-8514 Video Graph- 
ics Card. 


GetMaxColor Function Graph 


The GetMaxColor function returns the maximum valid color number (or palette 
size — 1) for the current graphics mode. This is valid in both high and low resolution 
modes. Thus, ina low resolution (320x200) mode, GetMax-Color will return a value 
of 3, one less than the number of colors in the predefined palettes. In high resolution 
modes such as EGAHI, the value returned will be 15 and, in monochrome modes 
such as ATT400HI, a value of 1 will be returned. 


Declaration: GetMaxColor: word; 
Example: 


uses GRAPH; 
var 
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MaxColors : integer; 


MaxColors := GetMaxColor + 1; 


Please note that normally the value indicates only the number of separate 
palette colors which can be used, not the maximum color values. Also, this function 
is not valid in the IBM8514 mode. See also SetColor. 


SetColor Procedure Graph 
The SetColor function selects the current drawing color or foreground color. 


Declaration: SetColor( Color: word ); 
Example: 
uses Graph; 
var 
ForeColor : integer; 


ForeColor := GetMaxColors; 
SetColor( ForeColor ); 


In low resolution CGA modes (320x200 pixel), the color selected is the palette 
color number, not the actual color value. In CGAC2 mode, SetColor(0) selects the 
background color (see SetPalette), SetColor(1) selects GREEN (color value 2), 
SetColor(2) selects RED (color value 4), and SetColor(3) selects BROWN (color 
value 6). 

In high resolution modes, the color values can be either the symbolic names 
(which are defined in the GRAPH unit) or the numerical values. If the SetPalette or 
SetAllPalette functions have been used to change the palette color values, the 
symbolic color names may not produce the expected results. 

The current color selected is used for drawing and for graphics text output. The 
current FillColor, however, may be different from the current drawing color (see 
Chapter 5). 

The colors selected are retrieved from a record of PaletteType as Pal- 
ette.Color|ColorNumber]. The PaletteType structure is defined in the GRAPH unit as: 


const 
MaxColors = 15; 
type 
PaletteType = record 
Site: s Otte; 
Colors : arrayl1..MaxColors] of shortint; 
end; 
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See SetPalette for predefined color palettes. See also GetColor and SetBkColor. 


GetColor Function Graph 


The GetColor function returns the current drawing (foreground) color. In low 
resolution modes using color palettes, the value returned will be the palette 
number, not the actual color value. 


Declaration: GetColor: word; 
Example: 
uses Graph; 
var 
ForeColor : integer; 


ForeColor := GetColor; 


In high resolution (16 color) modes, the value returned will correspond to the 
color values unless the SetPalette and SetAllPalette functions have been used to 
change the palette values. 

See SetColor for color values, and SetPalette for palette colors. See also GetBk- 
Color. 


SetBkColor Procedure Graph 


The SetBkColor function selects the background color values by changing the first 
entry in the active color palette (Palette.Color[0] := BackColor) to the specified color 
value (see also SetPalette). 


Declaration: SetBkColor( Color : word ); 


Example: 
uses Graph; 
var 
BackColor : integer; 


BackColor := 0; 
SetBkColor( BackColor ); 

When SetBkColor is called with a new value, the background color on the entire 
screen is changed. If this new background color corresponds to the color of an image 
already on the screen, the image will be invisible, though the image information 
will not be lost. When the background color is changed to a contrasting color, the 
invisible image will again become clear. 
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The argument BackColor can be either the symbolic color name or the color 
value. Table 20-1 shows how color names are predefined in the GRAPH unit. 


Table 20-1: Background Color Values 


Name Value Name Value 
Black 0 DarkGray 8 

Blue 1 LightBlue 9 
Green 2 LightGreen 10 
Cyan 3 LightCyan 11 
Red 4 LightRed 12 
Magenta 5 LightMagenta 13 
Brown 6 Yellow 14 
LightGray 7 White 15 


In low resolution (320x200) color palette modes, only the first entry in the 
palette (Palette.Color[0] ) can be changed (see SetPalette). 

In high resolution 16-color modes (EGA/VGA/etc.), all palette colors can be 
changed using the SetPalette or SetAllPalette function. However, if this is done, the 
symbolic color names may not provide the expected results. 


GetBkColor Function Graph 


The GetBkColor function returns the current background color value, not the 
palette entry number since the background color is always Palette.Color[0]. 


Declaration: GetBkColor: word; 


Example: 

uses Graph; 

var 
BackColor : integer; 
BackColor := GetBkColor; 


See also GetColor and SetBkColor. 


GetPalette 


The GetPalette function fills the Palette structure with current palette information 
(settings). 


Declaration: GetPalette( var Palette: PaletteType ); 


Example: 


uses Graph; 


var 


Palette 


PaletteType; 


GetPalette( Palette ); 


Here is the PaletteType structure: 


const 


MaxColors = 


type 


PaletteType 


end; 


Size 


Colors 
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record 
byte; 


arrayl1 
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oomaxColorsld of shortint; 


Palette.Size gives the number of colors valid for the current graphics driver and 
mode. Palette.Color is an array of Size bytes containing the color values for each 
entry in the palette. The default color values are shown in Table 20-2. 


Table 20-2: Color Values 


CGA 
Name 


Black 

Blue 

Green 
Cyan 

Red 
Magenta 
Brown 
LightGray 
DarkGray 
LightBlue 
LightGreen 
LightCyan 
LightRed 
LightMagenta 
Yellow 
White 


Value 


Oo CON A OF FP WN KK CO 


Pe ae > ame Ve Oe | 
or WN KK © 


EGA/VGA 

Name Value 
EGABlack 0 
EGABlue 1 
EGAGreen 2 
EGACyan 3 
EGARed 4 
EGAMagenta 5 
EGABrown 20 
EGALightGray 7 
EGADarkGray 56 
EGALightBlue 57 
EGALightGreen 58 
EGALightCyan 59 
EGALightRed 60 
EGALightMagenta 61 
EGAYellow 62 
EGAWhite 63 
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Most (if not all) EGA/VGA graphics cards will accept either the CGA or the 
EGA/VGA symbolic color names and color values appearing in Table 3-2. CGA 
graphics cards, however, may respond unexpectedly to the EGA/VGA color val- 
ues. 

See also GetPaletteSize, GetDefaultPalette, SetAllPalette, and SetPalette. 


GetDefaultPalette Function Graph 


The GetDefaultPalette function returns a palette definition record containing the 
palette information as it was initialized by the driver during InitGraph. 


Declaration: GetDefaultPalette( var Palette: PaletteType ); 
Example: 
uses Graph; 


type 
OrgPalette : PaletteType; 


GetDefaultPalette( OrgPalette ); 


See also GetPalette and GetPaletteSize. 


GetPaletteSize Function Graph 


The GetPaletteSize function returns the size of the palette color look-up table, 
indicating how many palette entries can be set in the current graphics mode. 


Declaration: GetPaletteSize: integer; 
Example: 
uses Graph; 
var 
PaletteSize : integer; 


PaletteSize := GetPaletteSize; 


SetPalette Procedure Graph 


With any of the 320x200 pixel video graphics modes (CGA, MCGA, or AT&T), color 
selections are limited to predefined 4-color palettes: CO, C1, C2, and C3. In each 
palette, the background color ( Palette.Color[0] ) can be user-defined, but colors 1..3 
cannot be changed. In every other graphics mode, all colors can be redefined. Table 
20-3 lists these predefined palettes. 


Declaration: SetPalette( ColorNum: word; Color: shortint ); 
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Example: 
uses Graph; 
balette_index, color : integer; 


SetPalette( palette_index, color ); 


Table 20-3: Predefined Palettes and Colors 





Palette | Color0 Color! Color2 Color3 

CO Black LightGreen LightRed Yellow 

C1 Black LightCyan LightMagenta White 

CZ Black Green Red Brown 

C3 Black Cyan Magenta LightGray 


SetAllPalette Procedure Graph 


The SetAllPalette function assigns NewPalette as the current palette with all new 
color assignment affected immediately. The color values for NewPalette must be 
assigned using SetPalette. 


Declaration: SetAllPalette( var Palette ); 
Example: 
uses Graph; 


type 
NewPalette : PaletteType; 


SetALlLPalette( NewPalette ); 


In low resolution (320x200) graphics modes using the predefined color palettes, 
the SetAllPalette command is not valid since only the background palette color is 
assignable. Changing graphics modes—as from CGACO to CGAC2—to change 
color palettes also erases (resets) the graphics screen. See also GetPalette. 


IBM-8514 Video Graphics Card 


The IBM-8514 video graphics card provides high-resolution color from an extended 
selection of color values. But the palette assignment tools used for more common 
resolution do not work for the IBM-8514 and; therefore, special functions are 
provided. 

The IBM-8514 graphics card and IBM8514 driver supports a color palette of 256 
colors chosen from a total of 262,144 (256K) color values. No symbolic constants 
are defined for this driver but the IBM-8514 card can also emulate VGA modes. 
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SetRBGPalette Procedure Graph 


The SetRBGPalette routine is provided for use with the IBM-8514 graphics card and 
IBM8514 driver, supporting a color palette of 256 colors chosen from a total of 
262,144 (256K) color values. 


Declaration: SetRBGPalette( ColorNum, RedVal, GreenVal, BlueVal: integer ); 
Example: 
uses Graph; 
var 
ColorNum, RedVal, 
BlueVal, GreenVal : integer; 


SetRBGPalette( ColorNum, RedVal, 
BlueVal, GreenVal ); 


The DetectGraph function will not identify the IBM-8514 card correctly but will 
instead identify this hardware configuration as VGA compatible. The VGA driver 
is recommended for maximum compatibility (see InitGraph) when the extended 
resolution of the IBM8514HI mode is not required. 

No symbolic constants are defined for this driver. Instead, each color is defined 
by three six-bit values for the Red, Green, and Blue components. 

The ColorNum argument sets the palette color (0..255) to be defined by the 
Red Val, BlueVal, and GreenVal arguments. Only the six most significant bits of the 
low byte of each color argument are used (values from 0 to 252 in steps of 4—for 
example, arguments of 252, 253, 254, and 255 are treated identically since the 6 most 
significant bits are the same). 

The other palette manipulation routines in the graphics library are invalid with 
the IBM8514 driver in the IBM8514HI (1023x768 pixel) mode. This includes SetA- 
llPalette, SetPalette, and GetPalette. Also, the FloodFill routine is not valid with this 
driver and mode. 


Chapter 21 


Screen Position Functions 


In graphics modes, the familiar 80 by 25 screen coordinates are replaced by pixel 
coordinates which, depending on the video hardware, may vary from 320 horizon- 
tal by 200 vertical to as high as 1,024 horizontal by 768 vertical (with newer and 
higher resolutions appearing almost daily). 

Because of the variety of screen resolutions, most graphics programs begin by 
checking the hardware for the appropriate drivers (see FirstGrp.PAS in Chapter 
18), and then using functions such as GetMaxX and GetMaxY to determine the 
screen size, adjusting subsequent operations to fit within these screen limits. 


GetMaxX and GetMaxY Function Graph 


The GetMaxX and GetMaxyY functions return the maximum x-axis and y-axis screen 
coordinate (maximum CP) for the current graphics driver and mode. For example, 
in EGAHI mode (640x350), GetMaxX returns 639 (0..639) and GetMaxY returns 349 
(0..349). Both are independent of viewport settings. 


Declaration: GetMaxxX: integer; 
GetMaxyY: integer; 

Example: 

uses Graph; 


var 
MaxX, MaxY : integer; 


MaxX 
MaxyY 


GetMaxX; 
GetMaxY; 
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See also Get ViewSettings, GetX, and Get Y. Similar information is available in 
text modes using the GetTextInfo function. 


GetX andGetY Function Graph 


The GetX and GetY functions return the current position in horizontal and vertical 
pixel coordinates. The returned coordinates are relative to the active viewport; if 
no viewport is set, the default viewport includes the entire screen. 


Declaration: GetX: integer; 
Get Y: integer; 
Example: 
uses Graph; 
var 
XPos.,, Y¥PoOs : integer: 


XPos 
YPos 


GetxXx; 
GetyY; 


See also Get Y, GetViewSettings, MoveRel, and MoveTo. Similar information is 
available in text modes using WhereX and WhereY. 


MoveTo Procedure Graph 


The MoveTo function moves the current position (CP) to the absolute screen pixel 
coordinates specified by (x,y), relative to the current viewport settings where (0,0) 
is the upper-left corner. The resulting CP is not limited by the current viewport 
settings or by the minimum and maximum screen coordinates. 


Declaration: MoveTo( X, Y: integer ); 
Example: 


uses Graph; 
var 
x5 -¥- ty otecer: 


MoveTot x,y 2; 


If no viewport settings have been made, the default settings include the entire 
screen. See also MoveRel. 
In text modes, GotoXY provides the equivalent function. 
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MoveRel Procedure Graph 


For graphics application, a relative move is often handier than an absolute move. 
For this, the MoveRel function shifts the new current position a relative distance 
from the old current position using the offset specified by (dx, dy). 


Declaration: MovekRel( dx, dy: integer ); 
Example: 
uses Graph; 
var 
dX, dY : integer; 


MoveRel( dX, dY ); 


The resulting CP is not limited by the current viewport settings or by the 
minimum and maximum screen coordinates. See also MoveTo. 


yey 





Chapter 22 


Pixel Drawing and Image Functions 


While lines and curves are useful for many drawing applications, some images can 
only be created by manipulating individual pixels. Of course, the line and curve 
functions could hardly operate without pixel write procedures. Also, by using pixel 
functions on a macro scale, entire images can be saved, rewritten, erased, or 
combined with existing screen images. 


Pixel Functions 


First are the pixel functions that provide the means to write individual screen pixels 
and to read the color values of existing screen pixels. 


PutPixel Procedure Graph 


The PutPixel function sets the pixel specified by (xpos,ypos) to the indicated color. 
In graphics modes using predefined palettes, color must be in the range 0..3, where 
0 provides the background color value. In full palette color modes, either the 
predefined color names from the Graph unit or the integer color values may be 
used. 


Declaration: PutPixel( XPos, YPos: integer; Color: word ); 


Example: 
uses Graph; 
var 
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XPos, YPos, Color : integer; 


PutPixett XPos, YPos, Color )> 


GetPixel Function Graph 
The GetPixel function returns the color palette index of the indicated pixel at (x,y). 


Declaration: GetPixel( XPos, YPos: integer ): word; 
Example: 
uses Graph; 
var 
AD VS FH teaer: 
Color: word: 


Color = GetPixel( X, Y ); 


Because the returned value is the palette index, the numerical value may not 
correspond to the actual color value, depending on palette assignments. See also 
GetImage and PutPixel. 


Line Drawing Functions 


Turbo Pascal provides three drawing functions—Line, LineTo, and LineRel—for 
making straight lines. The coordinate points used for these lines are integer coor- 
dinates (positive or negative) that are plotted relative to the current viewport 
coordinates, but which need not be restricted to the viewport limits. However, if 
the viewport ClipFlag is true, the lines drawn will be truncated at the viewport 
borders. 

If ClipFlag is false, lines are truncated only at the limits of the screen, even 
though the endpoint coordinates and the resulting current position may still lie 
outside the viewport and/or the screen limits. 

Two drawing modes are also supported: CopyPut and XOrPut. See SetWrite- 
Mode for details. 


Line Procedure Graph 


The Line function draws a line beginning at the first coordinate pair (XStart, YStart) 
and ending at the second coordinate pair (XEnd, YEnd), using the current drawing 
color, line style, and thickness. The CP is not changed. 


Declaration: Line( X1, Y1, X2, Y2: integer ); 
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Example: 
uses Graph; 
var 
XStart, YStart, XEnd, YEnd : integer; 


Linet XStaftt, Y¥Start, AEnd, YEnd 0; 


See also LineRel and LineTo. 


LineTo Procedure Graph 


The LineTo function draws a line beginning at the CP and ending at the specified 
coordinates (XPos, YPos). The current drawing color, line style, and thickness are 
used and CP is reset to (XPos, YPos). 


Declaration: LineTo( XPos, YPos: integer ); 
Example: 
uses Graph; 
var 
XPos, YPos : integer; 


LineTot XPoe, YRos >; 


See also Line and LineRel. 


LineRel Procedure Graph 


The LineRel function draws a line from CP to a point offset from CP by the 
horizontal and vertical distances specified by (dX, dY). The line is drawn using the 
current color, line style, and thickness. CP is updated to ( cp.X+dX, cp.Y+dY ). 


Declaration: LineRel( dX, dY : integer ); 


Example: 
uses Graph; 
var 
dX, ay « integer; 


LineRel¢ dX, @¥ 2; 


See also Line and LineTo. 


Line Styles 


For graphics drawing, two line thicknesses and several line styles are provided. 
You can also define a custom line style using a 16-pixel pattern. The line thickness 
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and pattern settings are used by the Arc, Bar, Bar3D, Circle, DrawPoly, Ellipse, Line, 
LineRel, LineTo, PieSlice, and Rectangle functions. 


SetLineStyle Procedure Graph 


The SetLineStyle procedure accepts three arguments setting the current line style, 
pattern, and width. 


Declaration: SetLineStyle( LineStyle, Pattern, Thickness: word ); 


Example: 

uses Graph; 

var 
LinePattern:.: word; 
Style, Width : integer; 


SetLineStyle(€ Style, LinePattern, Width ); 


Unless Style is specified as UserBitLn (value 4), which sets a custom, user- 
defined pattern, the LinePattern parameter is ignored and can be passed as zero. 

Tables 22-1 and 22-2 show how the constants for the style and width parameters 
are enumerated in the Graph unit. 


Table 22-1: Line Styles 


Name Value Description 
SolidLn 0 Solid line (default) 
DottedLn 1 Dotted line 
CenterLn 2 Centered dash line 
DashedLn 3 Dashed line 
UserBitLn User-defined style 





— 


Table 22-2: Line Widths 





Name Value Description 
NormWidth 1 1-pixel width (default) 
ThickWidth 3 3-pixel width 


A line width of 2 can be assigned, but any value greater than 3 will result in a 
graphics error, causing the line style and width to be set to the default settings. 

The remaining argument, LinePattern, is a 16-bit word defining a custom bit 
pattern to be used for drawing the line. The LinePattern argument is applicable 
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only if Style = UserBitLn (numerical value 4). If Style <> UserBitLn, then a Line- 
Pattern must still be supplied even though it is ignored. A zero entry is acceptable. 

When a user-defined pattern is used, each pixel corresponding to a one-bit in 
the pattern is turned on, pixels corresponding to a zero-bit are left off. Thus, if 
LinePattern = $FFFF, a solid line is drawn and, if LinePattern = $9999, a dashed line 
alternating two pixels on, two pixels off will result. For a long-dashed line, Line- 
Pattern = $FFOO or $FOOF might be used. If invalid parameters are passed to 
SetLineStyle, GraphResult will return a value of -11 (graphics error or generic error) 
and the current line style will remain in effect. 

See also GetLineSettings. 


GetLineSettings Procedure Graph 


The GetLineSettings function returns LineInfo with the current line style, pattern 
(upattern), and thickness. 


Declaration: GetLineSettings( var LineInfo: LineSettingsType ); 


Example: 
uses Graph; 
var 
LineInfo : LineSettingsType; 


GetLineSettings(€ LinelInfo ); 


The record structure LineSettings Type is defined in the Graph unit as: 


type 
LineSettingsType : record 
LineStyle : integer; 
UPattern : word; 
Thickness : word; 
end; 


See SetLineStyle for predefined styles and thicknesses. 


SetWriteMode Procedure Graph 
SetWriteMode sets the write mode for drawing operations. 
Declaration: SetWriteMode( Mode: integer ); 


Two constants are defined in the Graph unit as: 
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const 
CopyPut = OQ; { default } 
XO7r Put S13 


The CopyPut mode is the default. It uses the MOV instruction to write pixels 
directly to the screen during drawing operations, thus overwriting the existing 
screen image. 

The XOrPut mode setting uses the XOR instruction to combine the drawn 
image with the existing screen image. Using the XOrPut mode, drawing a figure a 
second time erases the image. 


Example: 
uses Graph; 


SetWriteMode( XOrPut ); 


SetWriteMode( CopyPut ); 


The SetWriteMode options affect only the DrawPoly, Line, LineRel, LineTo, and 
Rectangle routines. 


Rectangles, Bar Graphs, and Polygons 


While any of the following geometric forms can be created using the line drawing 
function, it is certainly more convenient to have functions that provide faster 
handling for common shapes. 


Rectangle Procedure Graph 


The Rectangle function draws a square or rectangle as defined by the corner 
coordinates passed as arguments. The figure is drawn using the current line style, 
thickness, and color. If one or more corners do not fall within the current viewport 
limits and the ClipFlag is set, then only the portion of the figure that fits within the 
viewport will be created. 


Declaration: Rectangle( X1, Y1, X2, Y2: integer ); 
Example: 
uses Graph; 
var 
XLeft, Y¥Top, XRight, YSottom = nteger; 


Rectangle XLeft, YToep, XRight, VYRottom ); 
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Bar Procedure Graph 


The Bar function draws a square or rectangle as defined by the corner coordinates 
passed as arguments. However, unlike the figure created by the Rectangle function, 
the Bar figure is not outlined but, instead, uses the current fill pattern and fill color 
(not the drawing color) to create a solid rectangle. For an outlined Bar, use Bar3D 
with a depth setting of zero. 


Declaration: Bar( X1, Y1, X2, Y2: integer ); 
Example: 


uses Graph; 
var 
XLeft, YTep, XRisght,. YSeELom, : integer; 


Bar( XLeft, YTop, XRight, YBottom ); 
See also GetColor, GetFillSettings, GetLineStyle, Rectangle, and SetFillPattern. 


Bar3D Procedure Graph 


The Bar3D function outlines a three-dimensional rectangular bar using the current 
line style and drawing color, then fills in the faces of the figure using the current fill 
pattern and fill color. 


Declaration: Bar3D(X1, Y1, X2, Y2: integer; 
Depth: word; Top: boolean ); 


Two constants are defined in the Graph unit as: 


const 
TopOn = True, 
TopOff = False; 
Example: 
uses Graph; 
var 


XLeft, YTop, XRight, YBottom : integer; 
Depth : word; 
TopFlag : boolean; 


Bar3p( XLeft, YTop, XRight, YBottom, Depth; Topflag >; 


The bar’s depth is given in pixels (normally about 25 percent of width) and is 
set back at an x/y ratio of 1:1 (approximately 45 degrees adjusted by the screen 
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aspect ratio). Since negative depths are not accepted, Depth is a (unsigned) word 
value rather than a (signed) integer value. 

If the TopFlag parameter is passed as false, no top is added to the bar, allowing 
bars to be stacked. 

If desired, a more elaborate figure can be created with each face of the figure 
filled with a different color and/or pattern using the FloodFill function. If this is 
desired, use the SetFillPattern function to select EmptyFill before calling Bar3D. 

See also Bar, GetColor, GetFillSettings, GetLineStyle, and Rectangle. 


DrawPoly Procedure Graph 


The DrawPoly function draws the outline of a polygon using current color settings 
and line style. 


Declaration: DrawPoly( Points: word; var PolyPoints ); 
Example: 
uses Graph; 
const 
Figurel : arrayl1..18] of integer = 
 600e TOU, TIO, Te0.. 100, Tae. tee. 125. 1460, 
TS ASO, Tee! Tees: TIS 120 EES TORS 180 32 
Figured : arrayl1..18] of integer = 
C 180700, 2190, 128, 200, 1303220) (125; 260, 
140: 420, T20,-8405 211055 2a05- tee eeu toe 2s 
var 
Points : word; 


Points = SizeOf(€Figure1)/(2*SizeOfCinteger)); 
DrawPolyCPoints,Figure1); 
DrawPoly(SizeOf(Figure2)/(C2*SizeOfCinteger)),Figure2); 


The Points argument gives the number of vertices for the polygon, while Poly 
points to a sequence of integer pairs, each pair defining the x/y coordinates for a 
vertex of the polygon. In order to draw a closed figure with N vertices, Points must 
equal N+1 and the final (Nth+1) coordinate pair must be equal to the first coordi- 
nate pair. 

In the example, Figurel defines a four-pointed star. Instead of assigning a 
constant to Points, the number of points in the figure is calculated from SizeOf(Fig- 
ure) divided by two times SizeOf(integer) since each point requires two integer 
coordinates. 
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The second figure, Figure2, changes the four-pointed star into an open line 
figure but is still created in the same manner. The vertex coordinates can also be 
assigned as pairs of PointType, thus: 


const 
Figurel : arrayl1..9J.of PointType = 
Cex7s 100 2¥ 2100) ,.¢x: F10)¥2 1200 ,(x:1002721302, 
Cx:1207y¥:2125),¢x:1402y¥2140),¢0x:1302¥3120), 
(x:140,y:110),¢€x:120;y:115),¢€x:100;y:100)); 
Figured : a#rpreyll..91] of. PointType = 
CCxs T003¥:100)0,¢Cxs210sy¥:120)7,¢x + 200742 1307; 
Cxs220sy2125),<x%4240 sy2140) , tx 28074147207; 
Cxs240 ¥ 27909 Cee! 0 y¥2115),¢€x1 22074: 1080) ) > 
var 
Points : word; 


Points = SizeOf(: Figuret ) 4 STtwedfC PointType): 

DrawPoly( Points, Figurel ); 

DrawPolyt Sizeoft Figure2e + *¢ SizeOft PointType. ); 
Figured ); 


This second example is functionally the same as the first; both draw identical 
figures. 

See also GetLineSettings, GetColor, FillPoly, SetGraphBufSize, and SetWrite- 
Mode. 


FillPoly Procedure Graph 


The FillPoly function draws the outline of a polygon using the current color settings 
and line style, and then fills the polygon using the current fill pattern and fill color. 


Declaration: FillPoly( Points: word; var PolyPoints ); 
uses Graph; 


const 
Figuretl : arrayl1..181] of integer: = 
C 5, "SR, FeO FO tee oe tee Pew 
150, 50; 100, -..0371-73; os eee ee ee 
Figured +: arraytl:.@]. of tnteger = 
Ln ' 3 S85. 108, 135°. Oo TRE eee ro 2k 


rTLULLPatyt Sizgeort « Figuret 2 £ 

Cc 2 * $tzeot( integer: } 33 3 teure? (2 
FiILLPoly(€ SizeOf (€ Figured ) / 

C 2 * Sitzedot( integer 743, 2-Frearee  F+ 
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The FillPoly function is called in the same fashion as the Poly function. 

In the example, Figurel defines a four-pointed star. Instead of assigning a 
constant to Points, the number of points in the figure is calculated from SizeOf( 
Figurel ) divided by two times SizeOf( integer ) since each point requires two 
integer coordinates. 

The second figure, Figure2, creates an open square. Note, however, that FillPoly 
will close the figure by connecting the start and end points, then fill the enclosed 
region. 

Unlike FloodFill, the fill algorithm used by FillPoly does not depend on a 
continuous outline to define the area, thus broken line styles are acceptable, and 
will simply fill the area defined by the polygon, which includes overwriting any 
other figure within the new boundary. 

If an error occurs, GraphResult returns —6 (out of memory in scan fill). 

See also DrawPoly, GetFillSettings, SetFillPattern, GetColor, and SetGraphBuf- 
Size. 


Video Aspect Ratio 


Each graphics driver and graphics mode has an associated aspect ratio, the ratio 
between vertical and horizontal pixel sizes and spacing. A figure which appears 
round on one screen (and graphics card /mode) may appear squashed or elongated 
using different graphics hardware. 

In order to ensure that geometric figures appear—more or less as intended—on 
the screen, the screen aspect ratio is used to calculate and correct the distortions 
created by differences in hardware and graphics cards. 


GetAspectRatio Procedure Graph 


The GetAspectRatio function returns two word values that can be used to calculate 
the AspectRatio for a particular graphics driver and graphics mode. 


Declaration: GetAspectRatio( var XAsp, YAsp: word ); 
Example: 
uses Graph; 
var 
xasp, yasp : word; 
ASDECTRAt 10: ©: reek; 


GetAspectRatio( xasp, yasp ); 
AspectRatio = xasp / yasp; 
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For example, using an EGA graphics card (EGAHi), an aspect ratio of 0.775 is 
found (xasp = 7750, yasp = 10000) since the EGA pixels are roughly 1/3 taller than 
they are wide. On the other hand, when using a VGA graphics card, the aspect ratio 
is found to be 1.000 (xasp = 10000, yasp = 10000) and the pixels are basically square. 
As you can see, there is a considerable difference between the two screen presen- 
tations. 

GetAspectRatio returns integer values for the x- and y-axis aspects with the 
aspect ratio calculated as xasp/yasp. 

This device aspect ratio is used automatically as a scaling factor with the Arc, 
Circle, and PieSlice routines to normalize the appearance of circles and circular arcs 
on the screen. 

With the Ellipse routine, the aspect scaling ratio must be specifically included; 
otherwise, no adjustment is applied. The aspect ratio can also be used with other 
geometric figures in order to correct scaling and appearance. 

The y-axis aspect factor is normalized to 10,000 and, in general, xasp <= 10,000 
(most screens’ pixels are taller than they are wide). 


Circles, Curves, and Arcs 


Curves are the hardest figures to create, requiring relatively complex calculations 
to determine the points composing them. Thus, the functions Circle, Ellipse, and 
Arc offer no small convenience in creating curved figures. 

The Circle function creates a complete circle, while Arc and Ellipse are called 
with start and end angles and may produce complete (closed) curves or only partial 
arcs. 

Also, the GetArcCoords function returns the start and end coordinates of the 
last call to Arc or Ellipse, allowing lines to be joined to the ends of arcs. The PieSlice 
function uses a combination of these capabilities to create an arc with lines drawn 
from the end points to the center. 

The start and end angles for Arc, Ellipse, and PieSlice are given in degrees, with 
0 degrees and 360 degrees at the right, 90 degrees at the top, 180 degrees at the right, 
and 270 degrees at the bottom. (See Figure 22-1.) 

To draw a closed arc or ellipse, simply specify a start angle of 0 degrees and an 
end angle of 360 degrees. Angles greater than 360 degrees can be used as arguments, 
but will be reduced to 0..360. For example, a starting angle of 300 degrees and an 
end angle of 450 degrees will draw an Arc from the 300 degrees point to the 90 
degrees point. 
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Figure 22-1: Drawing Arc Angles 





90° 


180° 
360° 


270° 


The angles for arc, ellipse and pieslice run counter-clockwise (widershins) beginning with 0°/360° at 
the right, 90° at the top, 180° at the left, and 270° at the bottom. 


Of course, the same Arc can be drawn by simply specifying 300 degrees and 90 
degrees as the start and end points. There is no inherent requirement for the end 
angle to be greater than the start angle, but allowing angles greater than 360 degrees 
can simplify many programming procedures. 

The Arc, Circle, Ellipse, and PieSlice functions do not use the current line style. 
All curves are drawn as solid lines using the current drawing color. 


Circle Procedure Graph 


The Circle function draws a complete Arc from 0 degrees to 360 degrees. The circle 
is drawn using the current drawing color, centered at the given screen coordinates, 
and using the radius specified (in pixels). 


Declaration: Circle( XPos, YPos: integer; Radius: word ); 
Example: 


uses Graph; 
var 
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XCenter, YCenter, Radius : integer; 


Circle(€ XCenter, YCenter, Radius ); 


since, unlike Ellipse, Circle is called with a single radius argument, the screen 
aspect ratio is automatically applied to adjust the results to produce a correct 
(circular) appearance. 

See also Arc, Ellipse, GetAspectRatio, and PieSlice. 


Arc Procedure Graph 


The Arc function draws a circular curve with the specified radius between the 
angles specified and centered at the given x and y coordinates. The start and end 
angles are in degrees (0..360). The center coordinates and radius are in pixels. The 
current drawing color and line style are used and correction for the screen aspect 
ratio is handled automatically. 


Declaration: Arc( X, Y: integer; StAngle, EndAngle, Radius: word ); 


Example: 
uses Graph; 
var 
XCenter, YCenter, 
StartAngle, EndAngle, Radius : integer; 


Arc(€ XCenter, YCenter, StartAngle, EndAngle, Radius ); 


See also Circle, Ellipse, GetAspectRatio, and PieSlice. 


Ellipse Procedure Graph 


The Ellipse procedure is similar to Arc except that separate radii are specified for 
the x and y axis. The elliptic arc is centered at the given x and y coordinates, 
beginning and terminating at the specified start and end angles and using the 
current drawing color. For a complete (closed) ellipse, use a start angle of 0 degrees 
and an end angle of 360 degrees. 


Declaration: Ellipse( XPos, YPos: integer; 
StAngle, EndAngle, XRadius, Yradius: word ); 


Example: 

uses Graph; 

var 
XCenter, YCenter, StartAngle, 
EndAngle, XRadius, YRadius : integer; 
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Ellipse(€ XCenter, YCenter, StartAngle, EndAngle, 
XRadius, YRadius ); 


Or: 


ElLlipse( XCenter, YCenter, StartAngle, EndAngle, 
XRadius, YRadius * AspectRatio ); 


Unlike Arc and Circle, correction for the screen aspect ratio is not applied 
automatically. If proportional radii, rather than specific pixel distances, are 
required, the y-axis distance should be adjusted as YRadius * AspectRatio, 

See also Arc, Circle, FillEllipse, PieSlice, and Sector. 


FillEllipse Procedure Graph 


The FillEllipse procedure operates similarly to the Ellipse procedure, but fills the 
drawn ellipse using the current fill color and style. The ellipse is outlined in the 
current drawing color. 


Declaration: FillEllipse( XPos, YPos: integer; 
XRadius, YRadius: word ); 
Example: 
uses Graph; 
var 
XCenter, YCenter, StartAngle, 
EndAngle, XRadius, YRadius : integer; 


FILLELLipse( XCenter, YCenter, 
StartAngle, EndAngle, 
XRadius, YRadius ); 


Or: 


FILLELLipse(€ XCenter, YCenter, 
StartAngle, EndAngle, 
XRadius, YRadius * AspectRatio ); 


See also Ellipse and Sector for more information. 


GetArcCoords Procedure Graph 


The GetArcCoords function returns the end points and center coordinates of the 
last call to Arc or Ellipse. 


Declaration: GetArcCoords( var ArcCoords: ArcCoordsType ); 
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Example: 
uses Graph; 
var 
ArcInfo : ArcCoordstType; 


GetArcCoords( ArcInfo ); 


The structure ArcCoordsType is defined in the Graph unit as: 


type 
ArcCoordsType : record 
kn VY § Tega 
RStart, YStert,; 
XEnd, YEnd : integer; 
end; 


The info structure defines the center point (X, Y) coordinates of the arc, the 
starting point coordinates (XStart, YStart, which are pixel coordinates, not the 
angle), and the end point (XEnd, YEnd) of the arc. These values can be used to draw 
chords, radii, or other lines meeting the ends of the arc and are also used by the 
PieSlice function. 

If the Circle function was the last curve function called, then GetArcCoords will 
return the center coordinates of the Circle while the (XStart, YStart) and (XEnd, 
YEnd) coordinates will be the 0 degree position on the Circle. 


PieSlice Procedure Graph 


The PieSlice function creates an arc, draws lines from the end points to the center 
point, and then fills in the completed PieSlice. 


Declaration: PieSlice( XCen, YCen: integer; 
StAngle, EndAngle, Radius: word ); 

Example: 

uses Graph; 

Var 


XCenter, YCenter, 
StartAngle, EndAngle, Radius : integer; 


PieSlice( XCenter, YCenter, 
StartAngle, EndAngle, Radius ); 
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The figure outline is drawn using the current drawing color and the current 
line style for the radius lines, then filled using the current fill pattern and fill color 
(see Flood Fill). Screen aspect ratio adjustment is automatic. 

See also Arc, Circle, Ellipse, and GetAspectRatio. 


Sector Procedure Graph 


The Sector procedure draws and fills an elliptical sector similar to the PieSlice 
procedure. 


Declaration: Sector( XCen, YCen: integer; 
StAngle, EndAngle, XRadius, YRadius: word ); 

Example: 
uses Graph; 
var 

XCenter, YCenter, 

StartAngle, EndAngle, 

XRadius, YRadius : integer; 


sector( XCenter, YCenter, 
StartAngle, EndAngle, 
XRadius, YRadius ); 


The figure outline is drawn using the current drawing color, using the current 
line style for the radius lines, then filled using the current fill pattern and fill color 
(see FloodFill). No screen aspect ratio adjustment is applied. 

See also Arc, Circle, Ellipse and PieSlice. 


Fill Patterns and Fill Colors 


Several functions, including FloodFill, GetFillPattern, GetFillSettings, SetFill- 
Pattern, and SetFillStyle, are provided to handle fill patterns, to fill enclosed areas, 
and to create custom fill patterns. 


FloodFill Procedure Graph 


The FloodFill function fills a bounded (enclosed) region that was defined by the 
specified border color (normally this will be the current drawing color). The 
(XPoint, YPoint) coordinates specify some point within the area to be filled, using 
the current fill pattern and fill color. 


Declaration: FloodFill( XPos, YPos: integer; BorderColor: word ); 
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Example: 
uses Graph; 
var 
XPoint, YPoint, BorderCetar : integer; 


FlLloodFEILS XPotnt, YPoint, Bordertolor 23 


If the start point is outside a bounded region, the exterior region (limited by the 
borders set by ViewPort) will be filled. If any break occurs in the line defining the 
region, the fill will leak. (Even a very small break will cause a leak.) 

For future compatibility, FillPoly is recommended wherever possible instead 
of FloodFill. If an error occurs, GraphResult will return a value of —7 (out of memory 
in flood fill). 

See also FillPoly, GetFillSettings, GetLineSettings, and SetGraphBufSize. 


SetFillPattern Procedure Graph 


The SetFillPattern selects an 8x8 user-defined fill pattern in the specified color. In 
the following example, Diamond is a sequence of 8 bytes, each byte corresponding 
to 8 pixels in the pattern. One bit turns on pixels, zero bits turn off pixels. The 
Diamond example pattern creates a small 7x7 diamond pattern with a one-pixel 
border at the right and bottom. 


Declaration: SetFillPattern( Pattern: FillPatternType; Color: word ); 
Example: 
uses Graph; 
const 

Diamond : arrayl1..8] of byte = 

C $710, $38, S7C, SFE, S$7C, S38, 310,. 300° 2? 

var 

Color : integer; 


SetFiltlPattern(€ Diamond, Color >); 


After SetFillPattern is called to establish the user-defined pattern, SetFillStyle 
must be called to make UserFill (12) the current pattern. A few other possible 
patterns are: 


const 
checker : arrayLl1..8] of byte = 
C SAA, $55, SAA, 955, :°SAAS O35, “SAN, °° 935 93 
chains’? : array(l1..8] of byte = 
C $6F, $40, SA0,. S40, “SAO, $40, S6F, $00 D3 
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chainsd : arraytl1..62 of byte: = 
(RoC, S69, SAU,  BF0): SG, SAG. 23C,; $C3 22 


See also GetFillPattern, GetFillStyle, and SetFillStyle. 


SetFillStyle Procedure Graph 


The SetFillStyle function sets the current fill pattern and fill color. Fill and drawing 
colors are separate and may have different values. 


Declaration: SetFillStyle( Pattern: word; Color: word ); 
Example: 
uses Graph; 


SetFillStyle€ SolidFill, GREEN ); 


Table 22-3 shows how fill patterns are defined in the Graph unit. 


Table 22-3: Fill Patterns 


Pattern Name _ Value Description 
EmptyFill 0 Background color 
Solid Fill 1 Solid fill 

LineFill 2 Fill with ——_———— 
LtSlashFill 3 Fill with //// 
SlashFill 4 Fill with ////, thick 
BkSlashFill _ Fill with \\\\, thick 
LtBkSlashFill 6 Fill with \\\\ 
HatchFill 7 Light crosshatch 
XHatchFill 8 Heavy crosshatch 
InterleaveFill 9 Interleaving lines 
WideDotFill 10 Wide-spaced dots 
CloseDotFill 11 Close-spaced dots 
UserFill 12 User-defined pattern 


All patterns except EmptyFill use the current fill color. Pattern 12 (UserFill) can 
only be called after SetFillPattern has established a user-defined fill pattern. 
See also FillPoly, FloodFill, GetFillPattern, and GetFillStyle. 


GetFillPattern Procedure Graph 


The GetFillPattern function returns the last fill pattern set by a previous call to 
SetFillPattern. 
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Declaration: GetFillPattern( var FillPattern: FillPatternType ); 


Example: 
uses Graph; 
var 
FilLPatternInfo : FillPatternType,; 


GetFillPattern( FillPatternInfo ); 


If no user-defined fill pattern has been set by a call to SetFillPattern, the 
FillPatternInfo array is returned filled with $FF. FillPatternType is defined in the 
Graph unit as: 


type 
FillPatternType = arrayl1..8] of byte; 


See SetFillPattern. 


GetFillSettings Procedure Graph 


The GetFillSettings function returns information in FillInfo about the current 
fillpattern settings. 


Declaration: GetFillSettings( var Filllnfo: FillSettingsType ); 


Example: 
uses Graph; 
var 
Fillinfo : FillSettingType; 


GetFillSettings( FillInfo ); 


The structure FillSettingType is defined in the Graph unit as: 


type 
FillSettingType : record 
Pattern © word; 
Soler word; 
end; 


The pattern record element returns a number value indicating a predefined 
pattern number only, not the pattern elements. 
See also GetFillPattern, SetFillPattern, and SetFillStyle. 
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The Internal Graphics Buffer 


As noted, several of the graphics functions can return error messages that indicate 
there is insufficient buffer memory to accomplish their tasks. When this happens, 
the SetGraphBufSize function can be used to allocate additional buffer memory. 


SetGraphBufSize Procedure Graph 


Several of the graphics routines use a memory buffer created by InitGraph with a 
default buffer size of 4K (4,096 bytes), sufficient to fill a polygon with roughly 650 
vertices. The buffer size can be decreased to save space or increased if more buffer 
memory is required. 


Declaration: SetGraphBufSize( BufSize: word ); 
Example: 
uses Graph; 
var 
BufSize : word; 


SetGraphBufSize( BufSize ); 


The SetGraphBufSize function must be called before calling InitGraph. 


Image Manipulation 


In addition to drawing functions, procedures are supplied for copying, erasing, 
duplicating and manipulating screen images. These are essential for any type of 
animation and, even for less elaborate applications, are useful in image replication. 


ImageSize Function Graph 


The ImageSize function returns the byte size required to store the bit image 
specified by the screen coordinates. If the size required for the image is greater than 
64K, a value of $FFFF (unsigned 65535 or signed —1) is returned. 


Declaration: ImageSize( X1, Y1, X2, Y2: integer ): word; 
Example: 
uses Graph; 
var 
Size : words 


Size = ImageSize( ulx, uly, Des, try) 


See also GetImage and PutImage. 
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Getimage 


The GetImage function saves the pixel image from the screen area which is specified 
by the four parameters. The InitSize function is used to calculate the required 
memory and the GetMem function allocates memory for image storage (memory 
allocation must be less than 64K). 


Declaration: GetImage( X1, Y1, X2, Y2: integer; var BitMap ): 
Example: 
uses Graph; 
var 
BitImage : pointer; 
XLeft, YTop, XRight, :V¥VBattonm.:.integer; 
Size < word; 


Size = ImageSize( XLeft, YTop, XRight, YBottom ); 
GetMem( BitImage, Size ); 
GetImage( XLeft, YTop, XRight, YBottom, BitImage% ); 


Notice the caret (*) appended to the Bitlmage parameter in the call to GetImage, 
indicating that the parameter is a pointer address rather than an array of bytes or 
a static variable. A similar notation is used with the Putlmage procedure. 

See also ImageSize and PutIlmage. 


Putlmage Procedure Graph 


The PutImage function writes a previously saved bit image to the screen with the 
upper-left corner of the image appearing at (XLeft, YTop). The Ops parameter 
controls how each image pixel (color) is combined with the existing screen pixels. 


Declaration: Putlmage( XLeft, YTop: integer; 
var Bitlmage; BitOp: word ); 
Example: 
uses Graph; 
var 
BitImage : pointer; 
XLett, YTop : tntecer; 
BitOp : word; 


PutImage( XLeft, YTop, BitImage, BitOp ); 


Table 22-4 shows how the BitOp options are defined in the Graph unit. 
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Table 22-4: Image Options 


Name Value Description 

CopyPut 0 Image is copied to screen, replacing existing pixels 
XOrPut 1 Image is eXclusive-OR’d with existing pixels 
OrPut 2 Image is inclusive-OR’d with existing pixels 
AndPut 3 Image is ANDed with existing pixels 

NotPut 4 Copies the inverse bit-image to the screen 


The PutDemo.Pas program will demonstrate how the various PutImage 
options operate. PutDemo is written for color monitors, EGA or VGA is preferred, 
but can be adapted to run on monochrome systems though the color overlay effects 
will not be markedly different. I suggest running the program as it stands, then 
experimenting with different color values, fill patterns, and copy options. 


The Image Copy Options 


CopyPut Each pixel in the image is mapped directly to the screen, replacing any 
existing image pixels. This includes image pixels that are blank (background). An 
entirely blank image can be used to “erase” other images or portions of the screen. 
More often, however, the XOrPut option is used to “unmap” an existing image. 


XOrPut Each existing screen pixel’s value is eXclusively OR’d with the corre- 
sponding image byte and the result is written back to the screen. When an image 
is XOR’d with a existing screen image, the result is a composite of the two. 


In PutDemo.Pas, notice how the LightCyan pixels (1011) XOR’d with the Blue 
(0001) background become LightGreen (1010) while LightRed XOR’d with Blue 
(0001) becomes LightCyan (1011) with the results appearing cleanly against the 
background image. 

If the same image is then XOR’d a second time, it effectively cancels itself bit 
by bit, leaving the original screen restored. This option is particularly useful for 
animation where an image needs to be written over an existing screen, then erased 
again to leave the original screen in place. 


OrPut This could also be called “Either/Or” since each image byte is OR’d with 
corresponding screen pixels and the result is then written back to the screen. 
Remember, each bit in each pixel is OR’d with the bits in the image so the result is 
a color composite of the background and the image. 
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Notice how, in PutDemo.Pas, LightCyan (1011) OR’d with Blue (0001) remains 
LightCyan (1011), while LightRed (1100) OR’d with the Blue (0001) background 
becomes LightMagenta (1101). 


AndPut With AndPut, the bits which are on in both the screen pixel and the image 
byte are also on in the result. The blank background in the Star image wipes out 
both the Box outline and the fill color except where the Star image actually overlies 
the Box. Also, the LightRed (1100) AND’d with LightBlue (1001) becomes DarkGray 
(1000). 


NotPut Thisisthesameas CopyPut except that the image is bit inverted—all Black 
(0000) pixels in the image become White (1111). The background image is overwrit- 
ten and lost. 


See also ImageSize and GetImage. 


{seeeeeeseszesses==} 
{ PUT-DEMO.PAS } 
{ Demonstrates } 
{ PutImage options } 
{seseeescesescesss=esz=} 
uses GRAPH, CRT; 
var 
GraphDriver, { graphics device driver 7 
GraphMode, { graphics mode value } 
MaxColors, { maximum colors available } 
ErrorCode integer; { reports any graphics errors } 
Star, Box pointer; { image pointers } 
function SavelImage( left, top, 
right, bottom integer 27 pointer ; 
var 
Image pointer; { Local image pointer } 
begin 
GetMem( Image, ImageSize( left, top, right, bottom ) ); 
GetImage( left, 
right, bottom, Image%* ); { save image} 
PutImage( left, top, Image*, XORPut ); { erase image } 


SavelImage := Image; 


end; 


procedure CreatelImages; 


{ return image ptr } 
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const 

pester 3 earrayl..1..9 >): OF Potnttyoe = 

CAE TOOS ye TOO), Cartes vetZou, C27 t002: yi 130), 
Cees Ve Is) ARS TOD ye Teli, Ce TO: otek, 
RETR VS TIOD, CxeTeDe yet Ib ds Cee 100s yi 100) y: 

pbox Ee errayt Teds Jot: Point t spe. 2 

C Ceetogs ys100),° CxetO0;. ys 16005) Cer TG0:. ¥3140)., 
ei Tees. ¥3 180), CxitTO0s vyet80) 3: 


. < 


begin 
setColor( LIGHTRED ); 
SetEILtStytet Linefttt, LIGHTCYAN )- 


FilLPoly(€ SizeOf(pstar) div SizeOf(Pointtype), pstar ); 


Star := Savelmage( 100, 100, 140, 140 ); 


setColor( LIGHTGREEN ); 

SetFitlstyle€ SolidFitl, LIGHTBLUE: >= 

FillPoly€ SizeOf(pbox) div SizeOf(Pointtype), pbox 22 
Box s= Savelmage( 100, 100, 140, 140 ); 


SetColort€ WHITE )+s 


PutImage (¢ 1» 10, S$ter*,.. CeopyPut : a 
GuttextaTt "60, 25, ‘+! ) > 
PutImage ¢ 80, 10» Box* 2 CopyPut be 
PutImage ¢ 200, 10, 80x", CopyPut ee 
PutImage( 200, 10) (Ster*,  €oovedt x 
Out rextxzy<-1350,. 25, ‘Cooyrut? 2: 
PutImage ( Op 6052 Stare; CopyPut rs 
CutPeciest (60, 755 "+! ry 
PutI mage ¢ au, 60, 86x"; CopyPut ae 
Putineget: 200, . 60, 8ox*, CopyPut Ris 
Putimeget:. 200, 60; Star’, AndPut ya 
OutTexeey< 130, (ee ‘ARGRUT . .23 
PutI mage ( Mx 410, Start, CopyPut be 
OutTextxy ¢ 60). T2553 rae ie 
PutImage ( Su, 140, B6x*%; CopyPut a3 
Putiviaget 200, 110). :80x%, CopyPut Te 
Putimaget «400, 110, Ster*, NotPut 2 
Outrextxy< 130, 125, "NOtPut!'. )3 
Putimagset. 310, 10, Star*,  'Convrut J 
OUTFERCR TG S60. 255 r+! ie 
PutImage( 380, 105: /Ban*, CopyPut + a 
PutImage ¢ 500, toy: Boe: CopyPut + 


7 
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Putimege( 500, 10, Star", OrPut 2 
Putimage(. 500, (10; Star*%, XOrPut - 
OutTextXY( 430, 15, ' CFPuE* 22 
OutTextxYt 430,. 235, : and * d; 
OutTextexy< 430, Foy [XG PPet* 22 
Putimaget 510, 60, Staer*, CopyPut ; 
OutTextxY¢( 360, 75, +! ie 
PutIimage(- 380, 60, Box’, CopyPut 12 
Putimage(€ 500, 60, ° 8ox*, CopyPut b 
PutiImage ¢ S00. 60, Star*, OrPut ee. 
GOutTextxyY¢ 439,. 3, 1 Morrie * <>} 2 
PutImage( 310, 110, Star%, CopyPut pe - 
OutTextxY¥¢ 360, t2é5, "4! is 
Putimage( 380, 110, Box%*, CopyPut : F- 
PutImage( 500, 110, Box%, CopyPut > 
PutImage( 500, 110, Star%, XOrPut ‘o- 
OutTextxY< 430, 125, 'XOrPut! 22 

end; 

procedure Initialize; 

begin { initialize graphics system and report errors } 


GraphDriver := DETECT; 


{ request auto-detect } 


InitGraph( GraphDriver, GraphMode, ATPASES. 2; 


ErrorCode := GraphResult; { test inita results } 
if ErrorCode <> grOk then £ if error during init + 
begin 


writeln(€' Graphics System Error: r 
GraphErrorMsg( ErrorCode ) ); 


ROLet  F.3 
end; 


MaxColors := GetMaxColor + 1; { read max color range } 


end; 


procedure Pause; 

var 
Ch ¢ ener. 

begin 
while KeyPressed do Ch 
Ch := ReadKey; 

end; 


begin 
Initialize; 
CreateImages; 


{ wait for key to be pressed } 


>= ReadKey; 


{ set graphics mode } 
{ create and save images } 
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Pause; 


CloseGraph; { restore text mode 
end. 


Chapter 23 


Graphics Text Functions 


Once a graphics mode has been set, the conventional text displays are no longer 
available and labels and text information can only be displayed using graphics text 
displays. In the graphics modes, however, graphics text display operates quite 
differently from conventional text display. 

For example, the conventional character screen positions (column and row 
coordinates) no longer apply and an individual character can appear almost 
anywhere on the screen, special provisions are required in order to track the screen 
display position and decide where the next display Line should appear, as well as 
to write graphics text to the screen. These include the OutText and OutTextXY 
functions. 

Also, since character sizes can be varied, different vertical and horizontal 
justifications are offered, and text can be displayed in both horizontal and vertical 
orientations, the Line offset and display positions become more than a little con- 
fusing. These variable settings are controlled by SetTextStyle, SetTextJustify, and 
SetUserCharSize. Because of these variables and complications, several functions 
have been provided to make it easier to keep track of display positions, font sizes, 
and string widths. These include GetTextSettings, TextHeight, and TextWidth. 


Text Functions 

Because of the elaborations of graphics string output, you should be able to write 
a string to the screen while in graphics mode before venturing into the esoterica of 
fonts, sizing, and orientation. 
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Unfortunately Pascal does not currently permit the creation of functions that 
accept a variable parameter list (as do the familiar Write and WriteLn procedures). 
Therefore, when program variables and other changing data are required to be 
written, alternatives which produce concatenated strings must be used—they will 
be demonstrated shortly. At the moment, the OutText and OutTextXY procedures 
provide the principal text output. 


OutText Procedure Graph 


The OutText function displays a string in the viewport (graphics window) begin- 
ning at CP. The current font selection, drawing color, character size, text orientation 
(direction), and justification are used. 


Declaration: OutText( S: string ); 


Example: 
uses GRAPH; 


OutText€ "Display string for viewport' ); 


If horizontal justification is LeftText and direction is HorizDir (default settings 
for graphics text display), CP’s x-axis coordinate is advanced by TextWidth( text- 
string ), otherwise the CP is not altered. 

See GetTextSettings, OutTextXY, SetColor, SetTextSettings, TextHeight, and 
TextWidth for related information. 


OutTextXY Procedure Graph 


The OutTextXY function displays a string in the viewport beginning at the coordi- 
nates specified by (x, y), which are relative to the viewport settings. The current 
font selection, drawing color, character size, text orientation (direction), and justi- 
fication are used. 


Declaration: OutTextXY( XPos, YPos: integer; S: string ); 
Example: 


uses GRAPH; 
var 
X, Y : Integer; 


OutTextXY( x, y, 'Display string in viewport’ ); 
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The current position’s coordinates are not affected. See also GetTextSettings, 
OutText, SetColor, SetTextSettings, TextHeight, and TextWidth. 


Graphics Text Styles, Justification, and Sizing 


Where conventional text modes offer the display equivalent of a typewritten page, 
graphics text modes come closer to providing a typeset display. And part and parcel 
of this enhancement are the capabilities to change fonts, select different horizontal 
and vertical justifications, to change character sizes, and even to run text displays 
vertically instead of horizontally. 


SetTextStyle Procedure Graph 


The SetTextStyle function sets the current graphics text font, the direction for the 
text display (horizontal or vertical), and the character size. 


Declaration: SetTextStyle( Font, Dir, CharSize: word ); 


Example: 
uses GRAPH; 
var 
CharSize : integer; 


SetTextStyle(€ Font, Direction, CharSize ); 
Table 23-1 shows how the standard fonts are defined in the GRAPH unit. 


Table 23-1: Graphics Text Fonts 








Name Value description 
DefaultFont 0 Bit-mapped 8x8 font 
TriplexFont 1 Stroked triplex font 
SmallFont 2 Stroked small font 
SansSerifFont 3 Stroked sans-serif font 
GothicFont 4 Stroked gothic font 


The DefaultFont is built into the graphics system. Of the other fonts, only one 
is normally kept in memory at any time. Also the .CHR files for the selected font 
must be located in the directory or subdirectory indicated by InitGraph as Driver- 
Path before the font can be loaded. 


422 USING TURBO PASCAL 6.0 





Multiple fonts, however, can be linked to your program using the BGIOBJ 
utility (see BGIOBJ Linking in Chapter 7). In this case, the RegisterBGIFont function 
is used to select the font required. 

By default, graphics text direction is horizontal, but can be set to vertical 
(rotated 90 degrees counterclockwise). The two graphics text directions are defined 
in GRAPHICS.H as shown in Table 23-2. 


Table 23-2: Graphics Text Direction 


Name Value description 
HorizDir 0 Left to right (default) 
VertDir = = 1 Bottom to top 


In vertical orientation, the text string begins at the bottom, and runs upward. 
No provisions currently exist for a string display running down the page or for an 
inverted string (upside down, running right to left), but these can be created if 
desired. 

For bit-mapped font(s), charsize may be 0..10. Values zero and one display 8x8 
pixel rectangles, value 2 displays a 16x16 pixel rectangle, continuing up to 10 times 
normal size. For stroked fonts, charsize = 0 magnifies the stroked font by the default 
factor of four or by the user-defined size factors set by SetUserCharSize. The 
maximum valid charsize is 10. 

If invalid values are passed to SetTextJustify, GraphResult will return —11 
(general error) and the current text settings will remain unchanged. 

See also SetTextJustify, TextHeight, and TextWidth. 


SetTextJustify Procedure Graph 


The SetTextJustify procedure selects horizontal and vertical text justification. The 
default values are LeftText, TopText (0,2). 


Declaration: SetTextJustify( horiz, vert: word ); 
Example: 


uses GRAPH; 
var 
hJustify, vdJustify : word; 


SetTextJustify( hJustify, vdustify ); 
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Constants for text justification are defined in the GRAPH unit as shown in Table 
23-3. 


Table 23-3: Graphics Text Justification 


Horizontal Justify Vertical Justify 
Name Value Name Value 
LeftText 0 BottomText 0 
CenterText 1 CenterText 1 
RightText 2 TopText Zz 


For horizontal justification, LeftText displays the text string to the right, starting 
at CP; CenterText displays the text string, centered at CP; and RightText displays 
the text string to the left, ending at CP. For vertical justification, BottomText aligns 
the bottom of the character string with CP, CenterText aligns the center of the 
display string at CP, and TopText aligns the top of the string with CP. See Figure 
23-1 for an example of this. 


Figure 23-1; Graphic Text Justification 


Toplext 


eftlext 
Center Text 
Rightlext 





Left 
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When justification is set as LeftText and direction as HorizDir, the current 
position’s x setting is advanced after a call to OutText by TextWidth( string ). 
See SetTextStyle for related information. 


SetUserCharSize Procedure Graph 


The SetUserCharSize procedure provides user-defined character magnification for 
stroked fonts only! This does not function with the DefaultFont characters and the 
font adjustment parameters are active only if SetTextStyle has been called to set 
charsize = 0. 


Declaration: SetUserCharSize( xMult, xDiv, yMult, yDiv: word ); 
Example: 
uses GRAPH; 
var 
xMult, xDiv, yMult, yDiv : integer; 


SetUserCharSize( xMult, xDiv, yMult, yDiv rhe 


When SetUserCharSize is called to select custom character scaling, the resulting 
width is defined as xMult/xDiv, while the resulting height is defined as 
yMult/yDiv. For example, to create a display with characters scaled to a height of 
3 (24 pixels) and twice as wide as they are tall (48 pixels), SetUserCharSize would 
be called with the following: 

xMult 6; XOIV =: 12 


yMult LB YOAV Ss: 13 
SetUserCharSize( xMult, xDiv, yMult, yDiv ba 


For tall, narrow characters the following call would be used: 
xMult 23.2 xDiv = 2: 

yMult = 6; VO FV Bibs 

SetUserCharSize( xMult, xDiv, yMult, yDiv ae 


and would produce characters 12 pixels wide and 48 pixels tall. 
See also GetTextSettings. 


Text Settings Information 


With the variety of choices in fonts, text direction, and vertical and horizontal 
justification, it is helpful to be able to find out what the current settings are and how 
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wide and tall a text string is. For these applications, three functions are provided: 
GetTextSettings, TextHeight, and TextWidth. 


GetTextSettings Function Graph 


The GetTextSettings function returns the TextInfo structure with the current font, 
direction, size, and horizontal and vertical justification. 


Declaration: GetTextSettings( var TextInfo: TextSettingsType ); 
Example: 
uses GRAPH; 
var 
TextInfo : TextSettingsType,; 


GetTextSettings( TextInfo ); 
The structure TextSettingsType is defined in the GRAPH unit as in the following: 


TextSettingsType : record 
Font 2 word; 
Direction : word; 
CharSize : word; 


Horiz : word; 
Vert 2 word; 
end; 


See also OutText, TextHeight, TextWidth, and SetTextStyle for further informa- 
tion. 


TextHeight/TextWidth Function Graph 


The TextHeight and TextWidth functions return the vertical and horizontal sizes of 
a string. 


Declaration: TextHeight( S: string ): word; 
TextWidth( S: string ): word; 

Example: 

uses GRAPH; 


var 
charheight, charwidth : integer; 


charheight = TextHeight( ‘Text String’: 2; 
charwidth = TextWidth(€ ‘Text String" ); 
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The TextHeight function returns the height of a string in pixels, using the 
current font size, scaling factors, and text direction. This may be the height of a 
single character or the height of an entire string. When a single character is used, 
an uppercase character is customary even though the returned information is based 
on calculated size and not the actual display size (for example, a “uw” will return the 
same size as “U”). 

The TextWidth function returns the width of a string in pixels, using the current 
font size, scaling factors, and text direction. This may be the width of a single 
character or, more often, the width of an entire string. 


Chapter 24 


Advanced Graphics Pascal 


Beginning with version 4.0 of Turbo Pascal, a graphics unit has been supplied 
(GRAPH.TPU) as a supplement to the standard function libraries. Unlike C com- 
pilers, Turbo Pascal does not require separate libraries for different memory models 
and the single instruction uses GRAPH; makes the graphics functions and defini- 
tions available to your program. 

And, because Turbo Pascal uses a smart linker, no penalties in memory require- 
ments, program size, or execution speed are incurred by including function units. 


Smart Linking 


In earlier versions of Turbo Pascal—and historically with other compilers—includ- 
ing special libraries imposed penalties in program size and memory usage because 
the entire library became part of the compiled program. This was true even when 
only one or two functions within the library were used or even if the library was 
not referenced at all. 

With smart linking, however, only those elements specifically needed by the 
program are included in the .EXE program. Likewise, data elements and constants 
that are provided by the library unit are included only if they are needed (and most 
constants, such as color names, are compiled as integer or word values in the first 
place). The savings realized by a smart compiler are not limited to the external 
libraries. These same criteria are applied to the program’s source code as well. 
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For example, suppose you have written a program and, during development 
and testing, you included a variety of special functions and procedures to report 
on what is taking place while the program is being tested. At the same time, in the 
program header, a large block of constants, string variables, and several data arrays 
are declared, again for use during testing and development. 

Of course, once the program is finished, these additions are not required and 
the obvious response would be to go through the program deleting these addenda. 

With smart linking, these special programming features can be left in place—in 
case of future need—and all that needs to be removed are the references which call 
the features. These can actually be commented out and left in place rather than 
deleted. When the program is compiled, all of these unreferenced blocks of source 
code will not be included and the constants, string variables, and data arrays—even 
though they appear globally in the program’s header—are also omitted. 

When compiling to memory instead of to disk, keep in mind that the smart 
linker is not enabled. Ergo, programs may be smaller when compiled to disk. 


Linking Graphics Drivers and Fonts 


By default, both Turbo Pascal and Turbo C use dynamically linked graphics drivers 
(*.BGI files) and graphics fonts (*.CHR files). While the use of external drivers and 
fonts offers advantages in limiting compiled program size and flexibility in adding 
new drivers and fonts at later dates, there are two disadvantages in depending on 
external files for operation. 

First, when using external drivers and fonts, the drive and directory path where 
the external utilities are located must be specified by the programmer at compile 
time (see InitGraph in Chapter 1). If the specified path or drive is changed later, the 
program must be recompiled with the new information. 

Second, while the .BGI and .CHR files can be distributed with your compiled 
program, these extra files are subject to accidental erasure and to other hazards, 
which can result in a dissatisfied end-user. 

But there is an alternative: linking the drivers and fonts directly as a part of the 
graphics library so no external files are required. After this is done, the drivers and 
fonts will be a part of the .EXE code produced by the compiler. 

The first step in linking driver and font files requires calling the BINOBJ utility 
to convert the .BGI and .CHR files into .OBJ files. The BINOBJ utility is distributed 
with Turbo Pascal and is described in the Turbo Pascal User’s Guide. Asample MAKE 
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source program, BGILINK.MAK, is included in the BGIEXAMP.ARC archive along 
with the demo programs, DRIVERS.PAS, FONTS.PAS, and BGILINK.PAS. 


Creating Driver and Font Units 


Turbo Pascal provides a stand-alone Make utility that is described in the Turbo Pascal 
User’s Guide, but which is essentially a utility accepting a series of macro instruc- 
tions for creating a program or a group of programs. 

The source file, BGILINK.MAK, which is included in the BGIEXAMP.ARC 
archive, contains instructions. These instructions create a series of .OBJ files from 
the .CHR and .BGI units and link these .OBJ files into two units: FONTS.TPU and 
DRIVERS.TPU. To use the BGILINK.MAK instructions, the MAKE.EXE and 
BINOBJ.EXE utilities (both distributed with Turbo Pascal) must be available either 
in the current directory or in a directory available through the DOS PATH defini- 
tion. 

The BGILINK.PAS, DRIVERS.PAS, and FONTS.PAS source codes (all included 
in the BGIEXAMP.ARC archive) must be in the current drive or directory together 
with all of the *.CHR font files and *.BGI driver files and, of course, the 
BGILINK.MAK file. 

Make is invoked from any DOS prompt using the instruction 


make -fBGILINK.MAK 


and interprets the instructions in the .MAK file, calling on Turbo Pascal to compile 
the DRIVERS.PAS and FONTS.PAS source programs and the BINOBJ utility to 
convert files into .OBJ files. After this is done, the DRIVERS.TPU and FONTS.TPU 


units may be included by any program in the uses statement, thus: 
uses Graph, Drivers, Fonts; 


As desired, the BGILINK.MAK source can be amended to include new fonts or 
to include new or custom drivers. Old fonts and drivers can be commented out if 
not needed but this is not necessary since only the fonts and drivers requested by 
the application program will be linked in the final .EXE program. 


Using Linked Drivers and Fonts 


Before the staticly linked graphics drivers and fonts can be used by a program, there 
is one other requirement that does not occur when using external drivers and fonts: 
the driver(s) and font(s) must be registered before calling InitGraph. 
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RegisterBGIDriver Function Graph 


The RegisterBGIDriver function is used to register a statically linked graphics 
driver. If the specified graphics driver is not found, a negative error code is 
returned; otherwise, the internal driver number is returned. Table 24-1 lists the 
graphics drivers and their corresponding symbolic names. 


uses GRAPH; 


if RegisterBGIDriver( @NameDriverProc ) < Q ) 
then: hattt 1: 2s 


Table 24-1: Graphics Drivers 








Driver Symbolic Name! 
CGA.BGI CGADriverProc 
EGAVGA.BGI EGAVGADriverProc 
HERC.BGI HercDriverProc 
ATT.BGI ATTDriverProc 


PC3270.BGI PC3270DriverProc 
IBM8514.BGI_ IBM8514DriverProc? 


1, Driver symbolic names were assigned by instructions in BGILINK.MAK. 
2. The IBM8514 driver is not included in the BGILINK.MAK instructions as distributed. 


(SSSSs2SSSSeSSeSeeeeeeeseesssessse=e=z} 
{ DRIVER.INC == calls RegisterDrivers } 
(S=SSSSSSSSSS5SS5eSeeeeeeeeeeseesee====} 


uses Graph, Drivers; 


procedure AbortDriver( FontName : string ); 
begin 
writeln€ FontName, ': ', GraphErrorMsg( GraphResult ) 3 
aN 9 9 Seay eae Le 
end; 


procedure RegisterDrivers; 
begin 
if RegisterBGIDriver( @CGADriverProc ) < Q 
then AbortDriver( 'CGA' ); 
if RegisterBGIDriver( @EGAVGADriverProc ) < Q 
then AbortDriver( 'EGA/VGA' ); 
if RegisterBGIDriver( @HercDriverProc ) < Q 
then AbortDriver( 'Herc' ); 
if RegisterBGIDriver( @ATTDriverProc ) < 0 
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then AbortDrivert "ATT". 2d; 
if RegisterBGIDriver( @PC3270DriverProc ) < 0 
then AbortDriver( "PCS270" dF 
if RegisterBGIDriver( @IBM8514DriverProc ) < 0 
then AbortDriver( 'IBM8514' ); 
end; 


begin 
RegisterDrivers; 
initialize; 
CloseGraph; 

end; 

RegisterBGiFont Function Graph 


The RegisterBGIFont function is used to register a linked stroked font character set. 
If the specified font is not found, a negative error code is returned; otherwise, the 
registered font number is returned. See Table 24-2 for a list of the graphics fonts. 


uses Graph; 


if RegisterBGIFont( NameFontProc ) < 0 then halt(1); 


Table 24-2: Graphics Fonts 


Font File Symbolic Name 
TRIP.CHR TriplexFontProc 
LITT .CHR SmallFontProc 


SANS.CHR SanSerifFontProc 
GOTH.CHR GothicFontProc 


Note: symbolic font names were assigned by instructions in BGILINK.MAK. 


ee 
{ FONTS.INC == calls RegisterFonts } 
ee 


uses Graph, Fonts; 


procedure AbortFont( FontName : string? 
begin 
writeln( FontName, ': ', GraphErrorMsg( GraphResult ) ),; 
hal et  F..2% 
end; 
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procedure RegisterFonts 
begin 
if RegisterBGIFont( TriplexFontProc ) < Q 
then AbortFont( ‘Triplex! ); 
if RegisterBGIFont( SmallFontProc ) < Q 
then AbortFont( 'Small' ); 
if RegisterBGIFont( SanSeriffFontProc ) < 0 
then AbortFont( "Sans Serif! ); 
if RegisterBGIFont( GothicFontProc ) < Q 
then AbortFont( 'Gothic' ); 
end; 


begin 
RegisterDrivers; 
RegisterFonts; 
Initialize; 


CloseGraph; 
end; 


User-Designed Drivers and Fonts 


Two procedures are supplied to permit the installation of user-defined or vendor- 
supplied device drivers or graphics fonts. Both of these procedures are described 
in extensive detail in the Turbo Pascal Reference Guide and are given a brief 
mention here because of limited applicability. 


InstallUserDriver Function Graph 


The InstallUserDriver function is used to register a vendor-supplied graphics 
driver. 


uses GRAPH; 


var 
Driver : integer; 


Driver = InstallUserDriver( "XGA', nil ): 


The Name parameter is the filename of the external device driver and Auto- 
Detect (nil in the example) is a pointer to an optional autodetect function which 
may not be included within the driver. 

The InstallUserDriver function returns an integer value for the default video 
mode for the new driver or, if an installation error occurs, an error value. 
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InstallUserFont Function Graph 


The InstallUserFont function is used to register a user-defined or vendor-supplied 
stroked font. 


uses Graph; 


var 
FontName : string; 
FontNum : integer; 
FontNum := InstallUserFont( FontName ); 


The InstallUserFont function is used to register any stroked font not included 
in the BGI graphics system. If the specified font is not found, a negative error code 
is returned; otherwise, the registered font number is returned. If the internal font 
table is full, a value of 0 (default font) will be reported. 
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Chapter 25 


Combining Text with Graphics 


In previous chapters, I’ve discussed the various Turbo Pascal graphics commands 
and briefly illustrated many of them. In this section, these commands will be used 
to create graphics and utilities and to demonstrate how various procedures and 
applications can be created. 

These demonstrations will include combining text and graphics, creating two- 
and three-dimensional graph displays for business applications, simple animation 
techniques, turtle graphics, image manipulation and rotation, image file storage, 
and using a mouse with graphics displays. Since programs must operate on a 
variety of hardware with varying resolutions and color capabilities, techniques for 
adapting to various hardware will also be demonstrated. 

Also, since the release of Turbo Pascal 5.5, Pascal has become object-oriented; 
therefore object-oriented programming techniques will be incorporated in graphics 
applications in Part 3. 

Space limitations restrict the extent and number of graphics programs which 
can be presented here. However, additional material, including Turtle Graphics, 
simple animation, printer and plotter output, control buttons, scrollbars, icons and 
fractals, can be found in Graphics Programming In Turbo Pascal 5.5, also available 
from Addison-Wesley Publishing Co. 


Caveat 
Most of these demonstrations have been created specifically for use with EGA or 


higher resolution graphics hardware using a color monitor. When practical, addi- 
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tional code has been included for adaptation to CGA or monographic equipment 
but, in many cases, some modification of the source codes may be necessary for 
lower resolution modes. 

While lower resolution and monochrome equipment is graphics capable, 
640x350 color provides a good minimum standard for demonstrating graphics 
applications. If these applications and demonstrations were written to operate only 
under the restraints and limitations of the lowest common resolutions and color 
capabilities, a great deal of real capability would simply be ignored. 

Thus, the EGA vertical resolution of 350 pixels and the VGA vertical resolution 
of 480 pixels provide space to show far more detail than is possible with CGA’s 200 
pixels (though the 1,024 vertical resolution of the IBM-8514 would be nice). At the 
same time, a palette of 16 colors certainly shows more visual information than 
monochrome. Therefore, the utilities demonstrated will make use of these capabil- 
ities whenever possible—even though such resolutions may not be universally 
available. 

While some earlier computer designs did not differentiate between text and 
graphics, contemporary MS-DOS systems do not permit mapping the ROM-based 
character set(s) directly into a graphics display. To overcome this limitation, both 
Turbo Pascal and Turbo C provide a default bit-mapped graphics character set that 
is areplacement for the ROM character set, including the extended ASCII characters 
(ASCII $80..$FF) which provide foreign characters such as the English pound sign, 
the Japanese yen, the accented vowels, and the graphics and math characters. 

But the graphics character fonts are not merely a replacement for the ROM- 
based characters and, in graphics modes, text displays can be much more elaborate 
than is possible under text modes. 

Four “fancy” stroked typefaces—Gothic, Sans Serif, Triplex (Roman), and 
Small—are supplied as standard fonts and string character positions can be 
adjusted by pixel instead of character positions; both the default and the stroked 
typefaces can be enlarged up to 10 times their normal sizes; the stroked typefaces 
can be proportioned to be taller or wider; strings may be set flush left, centered, or 
flush right and displayed vertically as well as horizontally. 


Combining Text with Graphics 


While the default font is a fixed-width font (all characters are the same basic width), 
the stroked fonts are proportional (for example, a capital “W” is proportionally 
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wider than a lowercase “i”) and character placement and string spacing reflect 
these, providing a better appearance than typewriter style text. 

But there are also a few limitations. The two principal output functions OutText 
and OutTextXY each write a string to the screen; OutText using the default CP and 
OutTextXY accepting screen position coordinates for the text output. But both of 
these functions accept only a single string for output and there is no direct provision 
for printing variables or building strings for output as supported in text modes by 
the Write and WriteLn functions. 

Unfortunately, Turbo Pascal does not currently permit creating analogous 
functions accepting variable parameter lists to serve these same purposes. But there 
are other ways to produce similar results. 


Functions for Variable Output 


Since the OutText and OutTextXY functions will accept only a single string argu- 
ment for output, the simplest method of displaying variables is to create functions 
that accept variable arguments and return formatted strings which can be handled. 

Only two number-to-string functions are used here for illustration, but similar 
functions can be created to handle any type of special format. 


Integer-to-String Conversion 


The simplest case of a formatted output string is converting an integer value, which 
is done by the [25 function: 


function 12S( Val : integer ): string; 
var 
Buffer : string(l101]; 
begin 
str¢- Val, Buffer 27 
12S := Buffer; 
end; 


Since no width argument is used in the str procedure, the string result is 
unpadded and the returned string consists only of the integer characters represent- 
ing the value. 


Real-to-String Conversion 


Converting real values to strings requires a bit more information than converting 
an integer value. Therefore, the R2S function is called with two additional argu- 
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ments for the number of digits (overall width of the resulting string) and the 
number of requested decimal places. 


function R2SC Val: real; 
Digit, Decimal : integer ): string; 

var 

Buffer : stringl20]; 
begin 

str(€ Val:Digit:Decimal, Buffer ); 

R2S := Buffer; 
end; 


Calling R2S( 517.2345, 7, 3 ) returns the string 517.234, with the value in the 
fourth decimal place rounded to display only three decimals. A value of 517.2346 
would be rounded up to return the string 517.235. 

Unlike the [2S function, however, the results returned by R2S will be left-pad- 
ded with blanks to the requested digit width and right-padded with zeros to the 
requested decimal places. If the calling value is larger than the indicated digits, 
additional digits will be left-appended to display the string result. For example, 
calling R2S( 543217.2, 7,3) returns the string 543217.200, with a total width of 10 
places even though a width of only seven places was requested. (A buffer width of 
20 characters has been used to provide ample space for most values.) 

Additional information on string formatting by the str procedure can be found 
in the Turbo Pascal Reference Guide under the write procedure. 


Concatenating Strings for Output 


With the two string conversion functions, writing variables using OutText and 
OutTextXY becomes almost as convenient as it is in text modes with the Write and 
WriteLn functions. For example, 


Write eR Pee: yn ae eg oe ee 
and 
OUtTTOxtt. Rt Aet: oe RZ SEPT S115 8d ee +3 


produce the result 


Pt tsi 3.7619 926531 
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The only real difference between the two is that where the Write procedure 
accepts a variable parameter list, the OutText procedure was called with a single 
string produced by using the concatenation operator (+) and the R2S function. 

More complex output strings can be built in this same fashion, concatenating 
string references, elements from arrays of strings, products of formulas used as the 
arguments of the 12S and R2S functions—a bit more complicated than using Write 
and WriteLn perhaps, but with moderate care, not that difficult. 


Other Output Utilities 


Writing material to a graphics screen is only half of the task and it also helps to be 
able to erase material that is no longer desired or part of the screen where something 
new is about to be written. 

When a new string is written to the screen in conventional text modes, the 
existing material is simply written over, vanishing automatically as the new char- 
acters are assigned to each row/column position. In graphics modes, however, text 
output is drawn rather than written. New text written over existing text results, not 
in the new replacing the old, but in an overlapping combination of characters—a 
result which is usually more confusing than helpful. 

Occasionally, this overwriting could be useful, if only in a frivolous sense. One 
programmer, who is partially color-blind, found that he could use graphics mode 
to write two or three different texts to the same area of the screen resulting in a 
graphics mishmash that nobody else could read. By changing the palette assign- 
ments, each layer of text became plainly visible ... if only to color-blind individuals. 
But it is most often undesirable to overwrite characters; therefore, the EraseStr 
function is provided. 


The EraseStr Function 


The EraseStr function is provided to erase the appropriate area of the screen before 
writing a string to the screen. It is intended to remove a block of graphics back- 
ground that would interfere with the string image. However, this function can also 
be used to erase a string or portion of a string if necessary. 

To clear a space for an output string, EraseStr is called with the x-axis and y-axis 
coordinates that will be used to position the output string and with a copy of the 
output string itself. 


procedure EraseStr( xLoc, yLoc : integer; Txt : string J; 


440 USING TURBO PASCAL 6.0 








The first things EraseStr needs to know are the current text settings. This is 
information that may be available elsewhere, but rather than having to pass a great 
deal of information when EraseStr is called, it is much easier to let the procedure 
ask for its own copy of the data. Therefore, a local variable TextInfo is declared. 


var 
TextiInfo : TextSettingsType; 
XDim, YDim : integer; 
TextImage : pointer; 

The local variables XDim and YDim will be used for the string dimensions while 
the Texthmage pointer will be the key to rapid and effective erasure of a selected 
portion of the screen. 

EraseStr begins by checking the text justfication settings that are in effect, which 
assumes they will not be changed before the new string is written to the screen. 
begin 

GetTextSettings( TextInfo ); 

According to the text output direction, the x and y dimensions of the output 
string are assigned to the appropriate variables. Also, for horizontal output, the 
XLoc variable is decremented to provide a one-pixel offset for the erase area. For 
vertical output, the YLoc variable is incremented for the same reason. 


case TextInfo.Direction of 
Hori2b%r * begin 


XDim == TextWidth( Txt ); 
YDim := TextHeight( Txt ); 
cect: Xboee 23: 
end; 
Vertdir +: begin 

YDim = TextWidth( Txt ); 
XDim = TextHeight( Txt ); 
inet. Fbea. 23 


end; 
end; f{ case } 


In the next steps, XLoc is adjusted according to the horizontal justification 
setting. 


case TextInfo.Horiz of 
LeftText : {€ no adjustment } ; 
CanterText * dec€ Xloc, XOim div: 2.-); 
RighttText 4 det: XLee,) XO tH I? 
end; 1° case 3} 
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And YLoc is adjusted using the vertical justification setting. 


case TextInfo.Vert of 
BottomText : dec( YLoc, YDim ); 
CenterText. : dect\lecy Yow div. 2 i; 
TopTtext 4.4 no edjpustweaent: 2 ; 
end; { case } 


Before any attempt is made to erase a screen area, two tests are needed to ensure 
that the XLoc and YLoc coordinates fall within the valid screen area. If either XLoc 
or YLoc falls outside the screen area, then nothing would be erased from the screen 
because subsequent calls to the GetImage and PutImage functions would attempt 
to use coordinates that did not exist in video memory. If necessary, XLoc and YLoc 
are adjusted to lie within the screen limits and, at the same time, the XDim and 
YDim offsets are changed to compensate. 


while xloc < O do 
begin 

inet Akooc 23 

dec(€ XDim ); 
end; 
while yloc < OQ do 
begin 

inet: YLSE: 23 
dec(€ YDim ); 
end; 


Now it’s time to actually erase a block of screen. Begin by allocating memory 
for TextImage according to the screen area that will be cleared. The function 


ImageSize uses the XLoc, YLoc, XDim, and YDim variables to return an unsigned 
integer indicating the number of bytes required for the selected image. 


GetMem( TextImage, ImageSize( XLoc, YLoc, XDim, YDim ) ); 


Next, GetImage is called, storing the screen image in the memory area indicated 
by TextImage before PutImage returns the image using the XOrPut option, leaving 
the desired screen area blank. 


GetImage( XLoc, YlLoc, XLoc+XDim, YLloce+Y¥Dim, TextImage%* ); 
PutImage( XLoc, YLoc, TextImage*%, XOrPut ); 


Lastly, Dispose is used to release the memory allocated for TextImage. The 
TextImage pointer variable cannot be referenced outside of the EraseStr function. 
However, memory that has been allocated locally does remain allocated until it is 
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released—and it must be released while the TextImage pointer is still available— 
specifically, before exiting EraseStr. 


Dispose(€ TextImage ); 
end; 


When EraseStr is called again, a new block of memory will be allocated and a 
new TextImage pointer assigned. If memory were repeatedly allocated without 
being released, the system memory could be quickly exhausted and subsequent 
calls to this or other functions would produce error results. 


EraseBlock 


As an alternative to the image functions, the necessary screen area could have been 
erased by rewriting the individual pixels using the background color, for example: 


procedure EraseBlock( Left, Top, Right, Bottom : integer 
var 

ty fe eke Thteder: 
begin 

k := GetBkColor; 

for :-t° 8 Lett to Riteht: do 

for j := Top to Bottom do 
PUT ae hy ORS ke 23 

end; 


This second option does save the small amount of memory that is allocated in 
the preceding EraseStr function but, as a trade-off, it is considerably slower in 
execution than the GetImage and PutImage functions. 


Alternative Applications 


Earlier, I mentioned that the EraseStr function could also be used to erase a string 
or portion of a string. This statement was only half true: it can certainly be used to 
erase an existing string. The second application, erasing a portion of a string is 
slightly less practical since EraseStr was not specifically designed for this purpose. 

Still, both of these functions can be accomplished but there are a couple of 
prerequisites which must be recognized. 

First, the text style, fonts, and justification must be the same as when the string 
was originally written. Second, the original drawing color must be in effect. Third, 
the screen coordinates where the original string was written must be known. And, 
fourth, the string itself must be known. 
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If any of the first three items have changed, an attempt to erase an existing string 
or a portion of an existing string will have unexpected results. And, in graphics 
modes, there is no convenient method of reading a text string back from the screen 
as can be done in text modes. 

Now, assuming that the text settings and color are correct and that the original 
screen coordinates are known, the first question is erasing an existing string. This 
is a simple operation—just call EraseStr directly using the x and y screen coordi- 
nates and the string, and the appropriate area of the screen will be XOR’d with itself. 
This leaves the screen blank and ready for a rewrite. 

In the second application, erasing a portion of a string, the easiest method is to 
begin by erasing the entire string and then rewriting the portion of the string which 
is desired. While several elaborate schemes could be constructed for selectively 
erasing specific graphics characters or substrings, all of them would require far 
more processing and time; the preceding can accomplish the task quite promptly. 

Word processing, per se, is not the topic of this book and using graphics fonts 
and text display is hardly the simplest method of programming a word processor 
or similar application. However, you may find it necessary to employ text editing 
procedures along with a graphics application. If so, here are a few hints: 

The best probable approach would be to treat the screen image as a mapped 
copy of the actual text array in memory, using some indexing scheme to identify a 
correspondence between a “line” of text in memory and its graphics position on 
the screen. 

If the bitmapped DefaultFont is used, the screen position for any character is 
relatively easy to calculate since all characters are fixed width. If the stroked fonts 
are being used, then the TextWidth function is the optimum method for deciding 
where a particular string ends. 

Also, the screen cannot be scrolled up or down in the usual manner. While it is 
possible to use GetImage and PutImage to move a major portion of the screen 
image, the memory requirements can be excessive. If so, a simpler method is to 
move some smaller portion of the screen, using multiple moves to shift as much of 
the screen as necessary. 

A similar technique can be used for left and right scrolling. 


Automatic Erasure 


As a final provision, two simple procedures are created as analogs to OutText and 
OutTextXY: GWrite and GWriteXY. Both procedures require single string argu- 
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ments and produce the same display output as OutText and OutTextXY, but have 
the added advantage of erasing the underlying screen before drawing the new text 
string. 

Since the GWrite procedure is called without position parameters, the current 
position coordinates are retrieved as arguments for the EraseStr procedure using 
the GetX and GetY functions. 


procedure GWrite( TxtStr : string vp 
begin 
EraseStr( GetX, GetY, TxtStr ); 
OutText¢ Txtstr )» 
end; 


Since the GWriteXY procedure is called with position coordinates, these are 
passed directly to EraseStr and then OutTextXY is called instead of OutText. 


procedure GWritexY( XLoc, YLoc , integer; TxtStr : string 2 
begin 

Eraeestrt XlLec, VYloe, -TxtStr 

OutTextx¥( XlLoc, YLoc, TxtStr yy 
end; 


These are two simple enhancements that can be revised and improved in 
several fashions. 

For example, you might prefer to have the GWrite procedure update the current 
position to the end of the text line and create a new version, called GWriteLn, which 
resets the current position to begin a new line of text below the last. 

Of course, which position coordinate to update—the x-axis or y-axis—would 
depend on whether the text orientation is horizontal or vertical (but these are 
easily-implemented decisions and are left as an exercise according to your prefer- 
ences). 


Summary 


So far, you've seen the basic elements necessary for formatted graphics text output, 
including provisions to erase background images as necessary. While they are 
lacking fancy elaborations, these basic tools can be extended and improved in a 
variety of fashions including, if you are so inclined, creating a full-fledged graphics 
editor. 

The next chapter will use text labels together with business graph displays. 
While the EraseStr provisions demonstrated here are not used, text positioning 
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techniques will be an important element, particularly in the pie graph demonstra- 
tion. 


(saa aaSSSSSSSSSsSsSSssesssssssssssss=sss} 
{ GWRITE.INC } 
{ utilities for graphics text output } 
{Seer tSSeSeSSSSSseSSeSeseeeersesasse==== 


procedure EraseStr(¢ xLoc, yLoc : integer;Txt : string Pe 
var 

TextInfo : TextSettingstype,; 

XDim, YOR + Tateger; 

TextImage : pointer; 


begin 
GetTextSettings( TextInfo ); 
case TextInfo.Direction of 
HorizDir : begin 
XDim := TextWidth( Txt ); 
YDim := TextHeight( Txt ); 
dec XtLoc 2; 


end; 
VertDir : begin 
YDim = TextWidth( Txt 2; 
XDim = TextHeight( Txt ); 
inet ‘Yhoe¢e.2y 


end; 
end; { case } 
case TextInfo.Horiz of 
LeftText : € no adjustment } ; 
CenterText : dec( XLoc, XDim div 2 ); 
RightText : dec(€ XLoc, XDim 5 
end; { case } 
case TextInfo.Vert of 
BottomText : dec( YLoc, YDim ); 
CenterText : dec( YLoc, YDim div 2 ); 
TopText : { no adjustment } ; 
end; { case } 
while xloc < O do 
begin 
tinct Bioe: 77 
dec(€ XDim ); 
end; 
while yloc < 0 do 
begin 
met FOGEe "73 
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dect-YDim >; 
end; 
GetMem( TextImage, 
ImageSize( XLoc, YLoc, XDim, YDim ) pe 
GetImage( XLoc, YLoc, XLoc + XDim, YLoc + YDim, 
TextImage%* ); 
PutImage( XLoc, YLoc, TextImage*, XOrPut 23 
Dispose( TextImage ); 
end; 


procedure GWrite( TxtStr : string ); 
begin 
EraseStr( GetxX, GetY, TxtStr ); 
OutText¢ TxtStr ); 
end; 


procedure GWriteXY( XLoc, YLoc ; integer; 
TRUSTER 4 String ‘2s 
begin 
EraseStr(€ XLoc, YLoc, TxtStr ); 
OutTextXY( XLoc, YLoc, TxtStr ); 
end; 


Chapter 26 


Business Graphic Displays 


Business applications often require graphic displays to show sales figures, financial 
information, stock price fluctuations, and almost any other type of numerical data. 
The reasons for this demand of graphic displays are simple: first, a graph display 
makes information easier to understand than a column of figures; second, a graph 
offers convenient visual comparisons making trends, irregularities and shifts much 
more obvious than the numbers themselves and; third, graph displays are more 
impressive than alphanumerical displays. 

The business graphs demonstrated here have been created with visual appeal 
in mind, using colors and fill patterns where possible and, in some cases, have been 
designed more to be visually impressive than to be visually informative. Granted, 
this is a purely subjective distinction but it is also one which you will need to be 
aware of when creating graphs and selecting the styles of display, patterns, and 
colors to be used. 


A Cautionary Note 


When creating a graph display, restraint is the best virtue. It is not only possible to 
include too much information in a graph, but it is common for the resulting graphic 
display be rendered unintelligible by virtue of an excess of artistic style, informa- 
tion, and cross-correlation. 

Remember, the first purpose of a graph is to present information in a manner 
and style that shows convenient correlations between different figures. This pri- 
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mary function—information—should not be overshadowed and defeated by col- 
ors, patterns, labels, logos, or other elements intended to make the informative 
eye-catching. Concentrate on information first, entertainment second. 


Business Graph Demos 


While there are at least several hundred styles of business graphs, five basic graph 
displays will be illustrated in this chapter: pie graphs, bar graphs, multiple bar 
graphs, 3-D bar graphs, and line graphs. 

The first four graph types—pie, bar, multiple bar, and 3-D bar—have been 
combined in a single demo program, while the line graph demo is created sepa- 
rately for reasons that will be discussed later. Each of these first four graph styles 
will present the same data, but in a different format. The demo program will pause 
after each graph, waiting for a key stroke. The last graph demo (3-D) will show 
several displays with different depths, pausing after each display. 

The data used for the demo has been written as two arrays, one of integer and 
one of char. In actual practice, this information would normally be read from 
external sources such as spread sheet data, database files, internally created data 
arrays, or from data files specifically created by your own program(s). 


Accounts: :s)\arreylt 3.454148) of integer = 
CRS ye eae Sop lowe lt eee ES 1 ty: Be > 
Ae oy VER, WA) Sey 255 TOR Boy Bey 2 Poy 
(oer, Til, 65, Sty 14, Ntyoeel se. 1% he 
OTe Oy 100, 60,70) 42, ee Teer, 425) iY 
AccTypes:..:' array(l1..9].:04 STRS = 
ee Cg a RO LOP 5) UV Remry by een ee..  Sovmet* y 
‘Lease’, ‘'Tires', 'Paint', '™isc' ee 
The dummy data sets shown are figures for four years income for an anony- 
mous corporation, broken down by eight categories. This data was selected simply 
for simulation and you can experiment with the graph displays by changing the 
figures. 


The Pie Graph Displays 


Four separate pie graphs are created, one for each year’s data using the function 
DrawPieGraphs to position these four displays—see Figure 26-1. Three parameters 
are used, the first specifying the array index for the year, the second and third 
specifying the x and y screen positions where the pie graph will be centered. 
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procedure DrawPieGraphs, 
var 
i + Integer; 
begin 
ClearDevice; 
GraphDefaults; 
Rectangle( 0, 0, MaxX, MaxY ); 
PieGraph( 1, GetMaxX div 4, GetMaxY div 
PieGraph( 2, GetMaxX div 4, 3*GetMaxY div 
PieGraph( 3, 3*GetMaxX div 4, GetMaxY div 
PieGraph( 4, 3*GetMaxX div 4, 3*GetMaxyY div 
end; 


FP kf 
ws Nw WY NH 
“we “Se Ne Ne 


Figure 26-1: Pie Graphs 





Motor Motor 


Motor 





For CGA systems, a separate set of screen coordinates has been provided, but 
EGA or higher resolution with color is recommended. 
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When the PieGraph function is called, several local variables are established: 
Total is initialized as zero and will be used to determine the total value of all of the 
data elements so that the slices can be apportioned correctly; m is initialized as 135 
and will be used to position the year label; s and t are initialized as zero and will be 
used for start and terminate angles for each slice. 


procedure PieGraph( DataSet, x, y : integer ); 
const 

BlankLine = $0000; 
var 

1p ie he Oy fc oN ues VJust, 

Total, CapColor : integer; 

ArcRec : ArcCoordsType; 


The BlankLine variable is also initialized as zero and will be used to draw an 
invisible line for positioning labels around the pie graph. The elaboration of $0000 
is not actually necessary, a simple 0 would suffice, but to define a less empty line 
style, a four-digit hexadecimal specification is necessary and this form has been 
followed here. 

In the first step, all of the items for the current year (dataset) are totalled and 
the radius, r, is set to 1/4 of the total. 

m ss 7357 
Total t= 0; 
Tor: Vive S t46 9 do 
inc(€ Total, Accountsl€ DataSet, i J a: 
r s= Total div 4; 

Since I know that there are only eight items for each year, | used the actual 
integer in the loop. In other circumstances, the number of elements might vary from 
application to application, a different method of controlling the loop might be 
preferred. This could be done using an index element, Elements, thus: 


for i := 1 to Elements do 
Or by calculating the number of elements: 


for i := 1 to sizeofCAccounts)/ 
Years*sizeofCinteger) do 


Now that I have the radius, I’m going to put a year label on the screen before 
drawing the pie graph. Instead of arbitrarily positioning the label—and having to 
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create a new label position for each data set—I prefer to be able to calculate the 
proper position. 

Since I know the radius (r), I could calculate a position from this bit of data but 
[ have a more elegant method in mind. When PieGraph was called, the variable m 
was initialized at 135, an angle that will be toward the top left of the eventual pie 
graph. 

The line style is set to BlankLine, previously defined as $0000, and the fill style 
is set to 0 (EmptyFill) and fill color to 0 (Black). 


SetLineStyle( UserBitLn, BlankLine, NormWidth ); 
Set Fillstytet 0, 0 2; 


Next, the PieSlice function is called with the x and y center coordinates in order 
to draw a pie slice beginning at the angle m and ending at the angle m+1 with a 
radius of r+10. A minimum angle width of one degree is required or PieSlice will 
simply do nothing. Also, using a radius 10 pixels greater than will be used for the 
pie graph yields a position outside the eventual graph image. 


PieSltice( x, ¥y, mp, mel, rt+t0 J7 { min width 1 + 3 
GetArcCoords( ArcRec ); 


The pie slice drawn in this case will be invisible, but it does yield a screen 
position which can be retrieved by calling GetArcCoords. Before doing anything 
with this information, however, the current color, text style, direction, and justifi- 
cation need to be set. 


+ MaxColors > 4 then SetColor( White ); 
SetTextStyle( SansSerifFont, HorizDir,- €. 2d; 
SetTextJustify( RightText, BottomText a 


Now the OutTextXY function can be called with the xEnd and yEnd coordinates 
in ArcRec, and the year data, which is the Oth element in each Accounts|[DataSet], 
is written to the screen. 


OutTextXY( ArcRec.xEnd, ArcRec.yEnd, 
128( AccountsC DataSet, 11) ); 


Remember, GetArcCoords returns a data record which contains the start and 
end x and y screen coordinates for the last call to any of the Arc, Circle, Ellipse, or 
PieSlice functions. 

This particular method of calculation to determine an appropriate screen 
position for a label will be used several times while the pie graph is being drawn 
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in order to position a label correctly for each pie slice. Before proceeding, the default 
text style is selected and, if practical, the drawing color is reset. 


SetTextStyle( DefaultFont, Re ERED Pha eis 
if. MaxColors > 4 then SetColor( EGAYelLlow a 


At this point, the actual pie slices are drawn, again using a loop for a known 
number of data elements: 
$42 8% 
to—scugs 
for: 4-32 2) to: Odo 
begin 


The fill style and color are arbitrarily changed for each slice. In this application, 
on a monochrome system, the fill color setting can be ignored, though the drawing 
color is not so inconsequential. Also, the line settings are reset to a solid line before 
a new pie slice is created. 

SetFillStyle(€ i-1, i-1 ); 


if MaxColors > 4 then SetColor( White ) 
SetLineStyle(€ SolidLn, 0, NormWidth 1 


The end angle for the pie slice is calculated as the proportional angle. As you 
will notice, all of the calculations are being carried out as double values for accuracy, 
with the final result being returned to an integer value since the PieSlice function 
does not accept float or double. Also, the calculated value has been incremented by 
0.5 before truncation in order to round the results to the nearest integer instead of 
the next lower integer. 


inc€ t, round( 360 * (€ AccountsL Dataset, +. 3] 
A Va tad 2 it Oe 8 be 


If any angle is returned greater than 360 degrees, an unlikely error except on 
the final slice, then the value is arbitrarily fixed at 360 to prevent a confusing display. 
Likewise, if the last pie slice does not complete the Circle (if t is less than 360), then 
a correction is made to keep the pie graph neatly finished. This type of error is not 
unlikely when a number of angles are calculated, each being rounded to the nearest 
integer value—but the cumulative error should not exceed one degree per slice. In 
this example, a maximum error of 8 degrees would be possible. 


if t > 360 then t := 360; 
17C 4° ee and tt. <4 360") then st se S60; 
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Depending on your application, you may wish to arrange matters so the 
correction is added to the largest individual slice or to apportion the error among 
the various slices. 

Next, the actual pie slice is created using the x and y center coordinates, the 
start angle s, the end angle t and the radius r. 


Steel ical , Ve Be Seif 22 


Now it is time to reset the line style to BlankLine and reset the fill style and fill 
color to EmptyFill and Black. Also, the working CapColor is set to the bright 
equivalent of the fill color used for the last pie slice ( i+8 ) and, if practical, the 
drawing color is set to CapColor. 


SetLineStyle( UserBitLn, BlankLine, NormWidth ); 
SetFilitStyleC By 0 27 

CapColor := 1+8; 

if CapColor > 15 then CapColor := Caz 

if MaxColors > 4 then SetColor( CapColor pI 


At this point, the program is repeating the same operation that was used to 
position the year number before this pie eraph was started. There is, however, a 
slight difference. The angle m becomes the mid-angle between the start and end 
angles (s and t) of the current pie slice and an invisible pie slice is drawn. GetArc- 
Coords returns the screen coordinates for the endpoints of this invisible slice. 


mw ce rpoundt € t = 89 772) } 8:27 
PieSlicet( %,- ¥, My MmH1, FS DZ 

{ must have a minimum width of one degree } 
GetArcCoords( ArcRec ); 


The next step arranges the vertical and horizontal text justification settings so 
that the label for the current pie slice will be positioned appropriately outside the 
pie graph and OutTextXY is called to write the label AccTypesli] to the screen. 


if ArcRec.xEnd > x then HJust := LeftText 
else HJust := RightText; 
if ArcRec.yEnd > y then VJust := TopText 


else VJust BottomText; 
SetTextJustify( HJust, Vdust ); 
OutTextXY( ArcRec.xEnd, ArcRec.yEnd, AccTtTypeslCil 0); 


Last, the current end angle becomes the start angle for the next pie slice and the 
loop continues. 
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Ss ate, 
end; 
end; 
Exploded Pie Graphs 


The technique used to position the labels for the pie graph can also be used to 
produce an exploded pie graph, a pie graph in which one or more segments are 
offset from the center to emphasize a specific segment. In order to keep the 
symmetry of the overall pie graph, the offset must be at the correct angle, the 
mid-angle of the slice. The following example code will provide a five-pixel radius 
offset by first creating an invisible pie slice: 


SetLineStyle( UserBitLn, BlankLine, NormWidth ); 
SOTRILUStytet: 0, 0 2): 

ME eee. ey ech ta ee ine ee aa ae 

PieSlicet x, ¥, m, mel; 5 is 

GetArcCoords( ArcRec ); 


Then the fill style and drawing colors are reset: 


SOTPUCLStyteti 4a, 4 dy 
if€ MaxColors > 4 ) then SetColor( WHITE oe 
SetLineStyle(€ SolidLn, 0, NormWidth 2 


And the offset pie slice is created centered on the Arcrec coordinates of the 
invisible slice: 


PieSlice€ ArcRec.XEnd, ArcRec.YEnd, s, t, r ); 


Naturally, the label for this slice will also require its position to be calculated 
with the additional 5 units radius in order to be proportionally located. 


Bar Graphs 


While pie graphs are visually more impressive, bar graphs offer a clearer visual 
comparison of magnitude. Most often, bar graphs are drawn vertically, as in the 
demonstration program, but they may also be presented horizontally—see Figure 
26-2. 

While the PieGraph function does not compensate for horizontal resolutions 
less than 640 pixels, the BarGraph function does adjust the graphic presentation to 
fit both the vertical and horizontal resolutions of the screen and graphics mode in 
use, beginning by setting width to MaxX and height to MaxY. 
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procedure BarGraph; 

var 
i, dy Xe Xe PEL OR SYST ERs Top, Bottom, 
BarHeight, Width, Height, Left : integer; 


Figure 26-2: Bar Graphs 
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Now a viewport (window) is created, leaving a margin at the top which is 
necessary for the labels that later will be written along the side. Next, width is 
decremented by 30 to leave space for amount labels, the horizontal graph step 
(hStep) is calculated from the width variable to provide for 32 columns and the 
vertical step (vStep) is calculated from the height variable. Finally, the bottom 
variable is set to six times the vertical step (vStep). 


begin 
Width := MaxX; 
Height MaxY; 


Left := 0; 
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Top. <= 0; 
ClearDevice; 
GraphDefaults; 
SsetViewPort( Left, Topt+5, 
Left+Width, ToptHeight+5, False ); 


In this particular instance, the graph is being vertically divided into six incre- 
ments, each increment to be 25 units (which might be dollars, pounds, or yen in 
hundreds, thousands, or similar units). In an application where the range of values 
is not known in advance, you might prefer your program to test for the highest 
value, which would be displayed and then create graph increments accordingly, 
numbering the vertical scale marks as appropriate. (See the LineGraph function for 
an example.) 

Horizontally, the bars will be grouped in units of four, placing each type of entry 
from each of the four year’s data together. Thus, vertical markers are drawn every 
fourth hStep: 


dec( Width, 30. ); 
hStep Width div 32; 
vStep Height div 6; 
Bottom := vStep * 6; 
if MaxColors > 4 then SetColor( GREEN i 
1 s= Q; 
repeat 
Linet 4,.0,. 1, vStep *: & >> 
inc€ i, hStep * 4 ); 
until Tt * WStep *. 32> 


Horizontal scale lines are drawn for each vStep: 


if MaxColors > 4 then SetColor( CYAN bp 
1 eg 
repeat 
LUAet Cet) We tep..* 32, % 23 
inc 4, wStep >: 
until i > Bottom; 


And, with the scaling grid completed, the bottom variable is moved up one 
pixel so the bars will not overwrite the base of the erid: 


dec€ Bottom ); 
Now the drawing color, text style, and fonts are set and the unit increments (the 


horizontal lines) are labeled beginning with 150 at the top, decreasing in steps of 
25 until 0 is reached at the bottom. 
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i MaxColors > 4 then SetColor( WHITE - 
SetTextStyle( DefaultFont, HorizDir, Tey 
SetTextJustify( CenterText, CenterText 13 
for i := 0 to 6 do 
begin 
x hStep * S2¢e tS; 
y : i * vS&tep; 
Hut Textxry( ei Ve DESC S01 F259 2 be 
end; 


Now, with the background grid complete, it’s time to create the bars them- 
selves. The height of the bar is calculated as a vertical offset from bottom and scaled 
as 25 units per vertical step. 


for i s:= 2 to 9 go 
begin 
for j := 1 to 4 do 
begin 
BarHeight := Bottom - 
round( AccountsLjJCild * vStep / 25 ); 


If the current video system is color capable in high resolution, then a new 
outline color (drawing color) and fill color are used for each year’s bar. Otherwise, 
only the fill style is changed and the draw and fill colors are kept as White 
(MaxColors-1). 


i# MaxColors > 4 then SetColor( j+1 ),; 
if MaxColors > 4 
then SetFillStyle( i-1, jt9 ) 
else SetFillStyle( i-1, MaxColors-1 ); 


Even though a two-dimensional graph is being created, the Bar3D function is 
used, but with a depth of 0 specified. The Bar function does not draw an outline, 
but creates a bar using the fill style and color. Using the Bar3D function provides 
an outline in the current drawing color and creates a better appearance. 


Bar3DdD( Ci-2)*hStep*4 + (Cj-1)*hStepte, 
BarHeight, 
(i1-2)*hStep*4 + (j-1)*hStepthStep-2, 
Bottom, 0, False ); 
end; {fend of loop for .j 2 


As the last step within this loop, after each bar for the four years’ data have 
been drawn, the drawing color is reset to White and a label is written at the top of 
the bar graph column. 
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if MaxColors > 4 then SetColor( WHITE )-s 
OutTextxy¢ Ci-1)*hStep*4-hStep*2, 5, AccTypesLil ); 
end; { end of loop for ji } 


Finally, if high resolution and color are supported, then the four years (year 
numbers) are added to the screen, and colors corresponding to the drawing color 
and fill color are used for each year’s bars. If the system is monochrome, then there 
is relatively little purpose in this unless you simply want to show the years. You 
might, however, modify the code to draw a small block by each year number using 
the corresponding year’s fill style. 


xX := MaxX div 3; 

y := MaxY div 4; 

SetTextStyle( SansSeriffFont, PoOPtTeO irs «4 03 

TOO FFs toe (&- do 

begin 
if MaxColors > 4 then SetColor( i+1 2 
OutTextxY( x, y, 128( Accountsl Me ice wees 
inc€ x , TextWidth(C' ie eae 

end; 

end; 


Multiple Bar Graphs 


While combining several years’ data in a single bar graph allows for convenient 
comparison between different years, it also makes the comparison between differ- 
ent categories within each year difficult. There are times when separate graphs for 
each year are more useful (and sometimes more impressive) than a single combined 
graph and the DrawMultiGraphs function creates four graphs on a single screen, 
one for each year’s data. 


procedure DrawMultiGraphs; 
begin 
ClearDevice; 
GraphDefaults; 


MultiBarGraph( 1, 0, 0 i 
MultiBarGraph( 2, MaxX div DOs 3 
Mut tiBarGraeph<( 3, °0, many 63 ¥.:2-73 
MultiBarGraph( 4, MaxX div hy WORT G9 2° 33 


end; 


Like BarGraph, MultiBarGraph adjusts the graphic presentation to fit both the 
vertical and horizontal resolutions of the screen and graphics mode in use, begin- 
ning by setting width to MaxX div 2 and height to MaxY div 2-13. The height setting 
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includes a 13-pixel margin and the width includes a 30-pixel margin so that the 
several graphs do not butt against each other. 


procedure MultiBarGraph( DataSet, Left, Top : integer ); 
var 

Width, Height, i, hStep, vStep, 

Bottom, x, y : integer; 

Scale : reat; 


The viewport (window) and scaling factors are set up the same as in the 
BarGraph function, except that only eight bars will be arranged horizontally and a 
vertical scaling factor is calculated as the variable scale instead of executing a 
separate scaling calculation each time. 


begin 
Width soz MaxX div 2; 
Height := MaxY div 2 - 15; 
SetViewPort( Left, Topt5, 
LefttWidth, ToptHeight+5, False ); 
dec( Width, 30. 2; 
hStep Width div 8; 
vStep Height div 6; 
Bottom := vStep * 6; 
Scale W$tenp 7. 233 


Then a background grid is written with scale factors along the right margin. 


if MaxColors > 4 then SetColor( GREEN ); 
for + = @ to 8.do 
Line(' 1. * hSten; Of 4. *. nStep, vitep * 6.32 
if MaxColors > 4 then SetColor( CYAN ); 
1 ss @3 
repeat 
Linet O, 4p hStep * 8, °4".22 
iaet- 4, Sten 22 
wnAtit + > Battom; 


And the graph is created for the selected year’s data, similar to BarGraph but 
with one principal difference. Since single bars will need to be labeled and these 
will not be wide enough for horizontal text labels, the vertical text direction is 
selected, The labels will be written centered horizontally over each bar and flush 
against a point five pixels below the top of the viewport. (See Figure 26-3.) 

If you are using an EGA or higher resolution system, you should notice that the 
labels appear clearly in white even though some partially overlie a colored bar. This 
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was also the reason why the Bar function, instead of the Bar3D function, was 
used—because an outline might have made the overlying captions more difficult 
to read. In monochrome modes, however, this becomes a major problem. 


Figure 26-3: Multiple Bar Graphs 
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if MaxColors > 4 then SetColor( WHITE ); 
SetTextStyle( DefaultFont, HorizDir, 1 ); 
SetTextJustify( CenterText, CenterText ); 
Tor: 40 287 6-t6. 6::do 
begin 

X t= hS$tep * 8 +.15>% 

Yosh - TF vS tens 

Outrextxyt x, y, 128C°> 150 s-% B28) ) 3 
end; 
SetTextStyle(€ DefaultFont, VertDir, 1 ); 
SetTextJustify(€ CenterText, TopText ); 
for 1 °-se" £6°s 86 
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begin 
if MaxColors > 4 
then Set Fi LStvtet 2, ter 2 
else SetFillStyle( it+t1, MaxColors-1 ); 
Gar( € i = 4 >) * HStep + <2, 
Bottom - round( Scale*AccountslCDataSet,it11]-1 ), 
1 * hS$tep = 2, 
Bottom-1 ); 
OutTextXY( Ci-1)*hStep + hStep div 2, 5, 
AccTypeslCit1] ); 
end; 


Asa last step, the year data are written to each graph: 


SetTextStyle( SansSerifFont, HorizDir, 2 ); 

SetTextJustify( CenterText, BottomText ); 

eee. WiGtn div <2? 

y := Height div 2 - 4; 

OutTextXxY( x, y, 12S8¢€ AccountsE DataSet, 1 1 ) 2 
end; 


Improving the Monochrome Display 


There is a problem with monochrome display modes where a label overwrites a 
bar and is not legible. However, there is a simple method you can use with a 
monochrome display that cures this problem. 

First, in MultiBarGraph, add a variable declaration for an image pointer. 


Caption : pointer; 


The viewport, text, and color settings are made as before and the background 
grid lines are drawn. Then, in the loop before drawing the bar, EraseStr (defined in 
Chapter 8) is called to erase the area where the label will be written and the label is 
sent to the screen. 


for i := 0 to 7? do 
begin 
x := i * hStep + hStep / 2; 
y 32 5; 
EraseStr( x, y, AccTypesLit1] ); 
OutTextXY( x, y, AccTypeslit1] ); 


Next, memory space is allocated for the caption image: 


GetMem( Caption, ImageSize x, y, 
. TextHeight( AccTypeslit1] ), 
TextWidth( AccTypesLit1] ) ) ); 
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And, because horizontal justification was set to CenterText, x is offset by half 
the string height of AccTypes[i+1] to ensure that the correct image area is read. 


dec(€ x, TextHeight( AccTypeslLi+1] ) div 2 be 


Now the GetImage function reads the label image from the screen as Caption 
before PutImage uses the XOrPut option to erase the label momentarily. 


GetImage( x, y, 
xt TextHeight< AccTypes€14+12° 3), 
y+TextWidth( AccTypesLit+t1] ), 
Caption*® 2: 

Putimaget x, yy, Caption*, xoOrPut >: 


The bar is drawn as before: 


if MaxColors > 4 
then SetFillStyle€ i+1, i+1 ); 
else SetFillStyle(€ i+1, MaxColors1 ); 
Bar( i*hStept2, 
bottomscale*Accountsldataset,i+t1]1, 
Ci+T I *hStep2, bettomt -); 


And then PutImage is called again with the XOrPut option to eXclusively-OR 
the caption image with the screen image—with the result that the portion of the 
label which overlies a bar is now a visible black on white instead of an invisible 
white on white. 


PutImage( x, y, Caption’, XOrPut ); 
Finally, the memory allocated to Caption is released. 


dispose( Caption ); 
end; 

This same modification can be used with color displays, but the effects may not 
be precisely what you expect. Remember, eXclusively-ORing White with White 
produces Black, but eXclusively-ORing White with Blue produces Yellow. Inciden- 
tally, if you are using an EGA/VGA system, delete the line in the Initialize function 
in the GRAPHALL.PAS demo which reads: 


GraphDriver := DETECT; 
and add the instructions: 


GraphDriver := CGA; 
GraphMode := CGAHI; 


Chapter 26: Business Graphic Displays 463 


This will force your system to emulate a CGA system and demonstrate the 
difficulties ina monochrome display. This is also a good way to test your programs 
to see how they will execute on a CGA system without having to move them to 
another computer. 


Three-Dimensional Graphs 


While Turbo Pascal provides the Bar3D function to make a three-dimensional bar 
graph, actually creating a 3-D graph display can be slightly more complicated. In 
its simplest form, a 3-D bar graph would simply be a flat bar graph. Its bars are 
drawn with the illusion of depth using Bar3D, but with only a single horizontal 
row of bars. 

If you are going to use the three-dimensional effect, however, at some point you 
will want to display several rows of bars with the illusion of depth in the rows as 
well as the individual bars themselves; this creates further complexity. Figure 26-4 
shows these multiple bar graphs. 

First, the 3-D bars created by Bar3D can be generated with different depths. 
Second, for best appearance, a three-dimensional graph requires a threedimensio- 
nal setting with scaling lines and an overall appearance of depth corresponding to 
the depth aspect of the individual bars. Third, everything must be tied together in 
a consistent whole rather than appearing to be merely an assemblage of scattered 
parts. 

In a purely rational sense, a 3-D bar graph is not as informative as a series of 
flat bar graphs. Visually, it is difficult to discern clearly the relative heights of the 
various bars and precisely how a specific bar aligns with the background scale lines 
but the three-dimensional graph is visually very impressive—see Figure 26-4. 

Therefore, the same data that has been presented in the form of pie and bar 
graphs will now be displayed in the form of four rows and eight ranks of three- 
dimensional columns against a scaled three-dimensional field. Also, for purposes 
of demonstration, Graphs_3D will show the same graph data using a series of ZAxis 
depths in steps of 5, from 15 to 40 pixels (assuming adequate vertical resolution). 

The variables XAxis and YAxis, which are the horizontal and vertical scale 
increments, are assigned values scaled to fit within the current screen size limits. 
XOrg and YOrd provide the screen origin point for all three axes. The graph width 
(XWidth) and height (YHeight) are now set to multiples of XAxis and YAxis, which 
will remain constant, while ZDepth will be recalculated for each graph display as 
the ZAxis increment size is changed. 
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procedure Graphs3D; 
begin 
ClearDevice; 
GraphDefaults; 
XAxis := MaxX div 13; 
YAxis == MaxY div 14; 


ZAxis := 10; 
XOrg f=) Maxx div 3: 
YOrg 7= MaxY div 2> 
Scale := YAxis / 25; 
LARVS2 425353 
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Graphs_3D loops as long as the display produced by the ZAxis value does not 
exceed the screen limits. 


repeat 
ThreeDGraph; 
thet. TAxtsb,. 10-22 
until YOrgt4*ZAxis > MaxY; 
end; 


The ThreeDGraph function creates each graph display, beginning by clearing 
the screen and setting the z-axis depth (ZDepth) for the current ZAxis. 


procedure ThreeDGraph, 


var 
Xx, y : integer; 

begin 
ClearDevice; 
XWidth =s 8 © XAK16; 
YHeight := 6 * YAx18; 
ZDepth = & © ZAxts; 


A caption is displayed in the upper-left corner of screen, showing the current 
ZAxis size, the display background is created by GraphField, the scale lines for each 
axis are labeled by ShowLabels and, lastly, the bar graph elements are drawn by 
the ShowAccounts function and the program pauses for a keystroke before creating 
the next graph display. 


SetTextJustify( LeftText, TopText ); 
SetColor( GetMaxColor ); 
x s= 10; y $= 10; 
Out Textxyt xs vy "ZAsie c= * % P28 ZAKS dees 
GraphField; 
ShowLabels; 
ShowAccounts; 
Pause; 
end; 


The several elements of the overall graph display have been broken into 
separate tasks in order to reduce a complex program to manageable proportions. 
The GraphField Function 


The first of these tasks is the GraphField function which creates a three-dimensional 
backdrop for the graph, complete with grid lines for all three axes. If color is 
supported, then the FillPlane function is used to create three solid planes in blue, 
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red, and yellow—rather like three sides of a box—which will form the background 
for the display. FillPlane is simply a convenient enhancement of the FillPoly 
function. 


procedure GraphField; 
var 
1 §° 9nteger: 
begin 
if MaxColors > 4 then 
begin 
FIULPlane( XOrg, YOrg, 
XOrg+XwWidth, YOrg, 
XOrg+XWidth, YOrg-YHeight, 
XOrg, YOrg-YHeight, 
SOlLIGFILL, LightBlue ); 


FillPlane(€ XOrg, YOrg, 
XOrg-round(ZDepth/AspR), 
YOrg+ZDepth, 
XOrg-round(ZDepth/AspR), 
YOrg+ZDepth-YHeight, 
XOrg, YOrg-YHeight, 
SolidFill, LightRed ); 


FillPlane(€ XOrg, YOrg, XOrg+XWidth, YOrg, 
XOrg+XWidth-round(ZDepth/AspR), 
YOrg+ZDepth, 
XOrg-round(ZDepth/AspR), 
YOrg+ZDepth, 
SOLIGERLVG, Vetitow. 2: 
end; 


Next, three lines are drawn from the screen origin point at XOrg/ YOrg. If the 
background planes were created, these lines delineate the planes. If the system is 


using monochrome display, then these axis lines and the following grid lines will 
serve to create the backdrop. 


Line( X0Org, YOrg, { major xX 
XOrg+tXWidth, YOrg ); 

Linet XOrgq, Yorg, { major Y 
XOrg, YOrg-YHeight ); 

Line(€ X0Org, YOrg, { major Z 


XOrg-round(ZDepth/AspR), YOrgt+ZDepth py 


If you will notice, the z-axis line (above) is adjusted for the screen aspect ratio, 
Aspk. This same adjustment will appear in all “positioning” calculations involving 


axis } 


axis } 


axis } 
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the z-axis in order to keep the z-axis angle effectively constant (approximately 45 
degrees) for all screen resolutions. 


if MaxColors > 4 then SetColor(GREEN); 
i = XOrg + XAxis; { X-axis position Lines } 
repeat 
Linet i, Y¥Ora; T,ovVOrd=YNeight >; 
Line( i, YOrg, i-round(ZDepth/AspR), YOrgtZDepth i 
treet 15 KASAS FY 
until 1 > korg + RWidth; 


if MaxColors > 4 then SetColor( CYAN ); 
+ s@ YOra. =< YARIS? { Y-axis position Lines } 
repeat 
Linet 2GF05, te KOratekwidth, i 2; 
Line( XOrg, i, XOrg-round(ZDepth/AspR), i+ZDepth ys 
ect 4»: TERE 
until i < Y¥Org = ¥hetgnt; 
if MaxColors > 4 then SetColor( RED ); 
ij := ZAxis; { Z-axis position Lines } 
repeat 
Line( XOrg-round(i/AspR), YOrgti, 
XOrg-round(i/AspR)+XWidth, YOrgti ); 
Line( XOrg-round(i/AspR), YOrgti, 
XOrg-round(i/AspR), YOrg-YHeightti ); 
the €- 4, Tause 23 
untit .1.> Zdepth; 
end; 


The FillPlane Function 


The FillPlane function is simply a convenient method of passing a set of calculated 
points to be assigned to an integer array (polygon) before calling the FillPoly 
function. This is faster than using the FloodFill function and will be used several 
times in this demonstration program to fill large or small areas with either solid 
colors or patterns. The color value passed (FColor) is tested for validity and defaults 
to White if monochrome graphics are being used. 


procedure FillPlane( X1, Y1, X2, ¥25 °23,.-YS,>. 445-14, 
FStyle, FColor : integer ); 


var 
Polygon : arrayl1..10] of integer; 

begin 
Polygon(l1] := X11; Polygonl2] = Yt; 
Polygonl3] := X2; Polygonl4] mY es 
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PolygonC5] 
Polygonl7J] 


x3. PolygonLlé6] 
X4; PolygonLl8] 
PolygonL9] Polygonl1]; 
PolygonL101]: PolygonL[2]; 

if MaxColors < 4 then FColor := MaxColors - i; 
SetFillStyle(€ FStyle, FColor ); 

FEULPOLYt 5, Pelygon: ) >; 

end; 


Ss 
Y4; 


The ShowLabels Function 


The ShowLabels function displays labels for all three axes of the display, beginning 
with the vertical (y-axis) magnitude scales along both the right and left sides of the 
display. The right side positions are relatively easy to calculate since they are 
stepped from the YOrg position with an x-axis offset equal to XOrg + XWidth + 15. 

The left side, however, requires both a y-axis offset, which is easily calculated 
as ZDepth — i * YAxis and an x-axis offset (left from XOrg), which is slightly more 
complicated but is calculated as XOrg - ZDepth / AspR - 15. Remember, the 
ZDepth variable is plotted at an angle so the actual screen offset must be calculated 
using the screen aspect ratio AspR to maintain the 45-degree screen angle for the 
Z-axis. 


procedure ShowLabels; 
var 
te dpeky Ay ® 4 integer > 
begin 
SetTextJustify( CenterText, CenterText ); 
j := XOrg + XWidth + 15; 
lL := XOrg - round( ZDepth / AspR ) - 13°5 


for. tte Ft te 6 de 
begin 
k := YOrg - i * YAxis; 
OUTTOXERTE : F,. Ky F28C 1*257:) 32 
mos* YOrg + 2Depth = 41:* YAxds:s 
CUCTORTAYS ty mp TASC 4*25. 3°33 
end; 


The AccTypes labels are written horizontally across the top and bottom of the 
graph: 


if MaxColors > 4 then SetColor( LightBlue ); 
j XOrg + 25; 

L J - round( ZDepth / AspR ); 

m YOrg + ZDepth + 8; 
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k := YOrg - YHeight - 8; 

for i := 1 to 8 do 

begin 
OutTextxYt j, k, AccTypesli+ii 2; 
OutTextXY( L, m, AccTypesLit1] ); 
inet J, -30° 337 
inet Laces 

end; 


And the year dates are written at an angle along the z-axis: 


if MaxColors > 4 then SetColor( LightGreen ),; 
for i := 0 to 3 do 


begin 
j = XOrg - 
round( (te 3rAKessS + TAxis/2.) 7 AspR > + 2; 
m := YOrg + round( i*ZAxis + ZAxis/2 ),; 
k := m - YHeight; 


t j + XWidth; 
SetTextJustify( LeftText, TopText ); 
Out Textrve. tl, > Test Agcountsl 1442.°7.-357) 33 
SetTextJustify( RightText, BottomText ); 
OutTextxy( 1, €, T2SC Accountst tet, 1 T°) 0; 
end; 
end; 


The ShowAccounts Function 


The bars for each year could have been drawn using a double loop and increment- 
ing the colors for each year. Instead, four separate loops are used here permitting 
the assignment of specific colors for each year’s bars. 


procedure ShowAccounts; 
var 
1 * integer; 
begin 
if MaxColors > 4 then SetColor( EGAYellow ); 
for i 22 2 to v9 do 
begin 
AddBar( i-2, 0, round( Accounts(1,iJ * Scale es 
LightCyan, Cyan ); 
AddBar( i-2, 1, round( Accountsl2,i] * Scale ay 
LightRed, Red ); 
AddBar( i-2, 2, round( Accountsl3,i] * Scale : 
LightBlue, Blue ); 
AddBar( i-2, 3, round( Accountsl4,iJ] * Scate 2, 
LightGreen, Green ); 
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end; 
end; 


The AddBar Function 


The AddBar function is used to create and position the three-dimensional graph 
bars. The BarWidth and BarDepth variables, which set the size of the bar, are 
initialized as half the x-axis and z-axis step sizes. Making each bar smaller than the 
spacing between the bars offers a better visual effect and permits seein g “between” 
bars so that taller bars do not completely hide the smaller bars behind them. 


procedure AddBar( Left, Bottom, Height, 
Color?, Color2 : integer ): 

var 

Top, Right, BarWidth, BarDepth : integer; 
begin 

BarWidth := XAxis div 2; 

BarDepth <s= ZAxis div 2; 

if MaxColors < 4 then 


begin 
Color’ = MaxColors - 1; 
Color2 := MaxColors - 1; 
end; 


The fill style for each bar is incremented from left to right. If the display is in 
monochrome, this helps to make the several bars easier to distinguish. 


SetFillStyle(€ Left+1, Color1 ); 


The left and bottom variables began as integers in the 1..8 and 1..4 ranges and 
describe step positions but are now converted to the actual screen offset positions. 
Right and top provide the remaining corner parameters. 

Left °= AOrg + € Lett. * KAxis:) = 


round¢ ¢ < Bottom +: € 0:35 * ZAxits: ) 7: ¥Axise > 
© ARTE) Oo ROERR D2 


Bottom := YOrg tround( ¢ Bottom+0.70 ) * ZAxis 5 a 
Right = Left + BarWidth; 
Top = Bottom - Height; 


At this point, Bar3D could be used to create the display bars for this graph. 
However, there is one flaw in this: the z-axis angle produced by Bar3D does not 
always match the z-axis angle produced by the screen aspect. For this reason, Bar3D 
is called with a 0 depth and the FillPlane function is called to create each bar’s side 
and top. 
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Bar3D( Left, Top, Right, Bottom, 0, False 3 
FillLPlLane(€ Right, Top, 
Rightt+tround( BarDepth/AspR ), 
Top-BarDepth, 
Right+tround( BarDepth/AspR ), 
Bottom-BarDepth, 
Right, Bottom, 
(lLosedotritt, Cotlort 25 
FillPlane( Left, Top, Right, Top, 
Rightt+round( BarDepth/AspR ), 
Top-BarDepth, 
Left tround( BarDepth/AspR ), 
Top-BarDepth, 
Satigfiti. Cetlerd 23 
end; 


If you would like to experiment, simply comment out the two FillPlane calls, 
set Bar3D’s depth as BarDepth/AspR, and change the final parameter from 0 to 1 
to put a top on the bar. 


The Line Graph Display 


The previous demos used the same data set for each graph form. Line graphs, 
however, are normally used to show a half-dozen or fewer data sets with each 
containing a large number of sequential data points. For demonstration, four data 
sets will be used, each containing 20 sequential data points. As with the previous 
demo, for convenience, the data points are contained in a 4 by 20 matrix. In actual 
practice though, the graph data would probably be read from some external source 
or generated within the program. 


const 

Accounts : arrayl1..4,1..201] of integer = 
( € 446. 4275] 1320 Th0e 16) 2. 137% Theo 
135,,.933,;|/ 123, 21,5. 120,. leSs TT 43 

109, 219,| 122, 132, 140, 42 2 
C @?, B9,| 100. 8p e ya ese Ve bo 
148, 159,| 160, 168, “172, 167, 133, 

189,,. 1635. 165) 1355.1 ee 186 72 
¢ 89;  73y\- 66a We ee ee, 1 2 
45. €6;,|\. SP, 56g. 29555 89% 56; 

84. Shy SS, ~ Say - egw renee 
C 43, -485| 16, 195 228.5 Tits 
18, 49,| 24%, 24,  ROpseue ar) 
a2, 2B," 19, 235 .“855eR85 ) y We 
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Years : arrayl1..5] of integer = 
( 1985, 1986, 1987, 1988, 1989 ); 
AccTypes : arrayl1..4] of STRS = 
C 'GenMec', 'UnvEle', CeCe te ¢s ON CEREP! F, 

Again, to make the graph visually impressive, a set of four graphic images will 
be used in the plot and Createlmages is used to construct these. In other circum- 
stances, you might prefer to create a series of images separately and load individual 
images from disk as required. (For a simple image creation utility, see EditIcon.PAS, 
Chapter 15, Graphics Programming In Turbo Pascal 5.5.) Figure 26-5 shows the 
completed line graph display. 


Figure 26-5: Line Graphs 
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The Createlmages Function 


This function is used to generate and save a series of graphic images that will be 
used to emphasize points on the line graph. The array figure is a set of points 
describing a small stylized lightning bolt. 
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procedure Create_Images,; 
const 
Figure : arrayl1..16]. of integer -= 
. 493 S.° 4ay. By Veer ter es. Tey 
10, “48. Tey ASe Cree 455 Th, (309% 
var 
+ =: integer; 


The wheel or gear image is created from a series of small pie segments. Please 
realize that any small arc figure will be grainy. For a small detailed figure, the 
IconEdit utility can be used to create either a disk bit-image or a program listing 
that can be included in your application source code. 


begin { wheel / gear } 
SetFillStyle€ EmptyFill, 0.0; 
if MaxColors > 4 then SetColor(¢ 10 ); 
for i i=2:°0 to 3 do 
PieSlice€ 10, 10, i*60, (41%60):4+60,.;.10) 3 
GetMem( Grimagel1], ImageSize( 0, 0, 20, 20 ) ); 
GetImage( 0, 0, 20, 20, Grimagel1]* ); 
PutImage( 0, O, Grimage[11%, XOrPut ); 


The lightning bolt image uses the data points in Figure and the FillPoly function 
with the fill style set to Empty Fill. 


{ Lightaning tote + 
if MaxColors > 4 then SetColor( 11 ); 
FILLPoly( SizeOf( Figure ) div 
( 2 *® Sizedf( integer ) 3, Figure )7 
GetMem( GrimagelL21], ImageSize( 0, 0, 20, 20 ) ); 
Getlmage( 0, 0, 20, 20, Grimagel21%* ); 
PutImage( 0, O, Grimagel2]*%, XOrPut ); 


The oil drop image is created in outline by the Arc and Ellipse functions. Then 
FloodFill is called, using SolidFill and the current (drawing) color, to complete the 
image. 


{ o1t drop: + 
if MaxColors > 4 then SetColor( 12 ); 
Are(: 10, 10, 105, .360,-8 23; 
EtLipset 0, -5,5. 300, 90, 8, 3 2; 
Eitipset. 3, 19, 0; 90, 16, 6 .23 
SetFillStyle( SolidFill, GetColor ); 
FloodFILL¢( 10, 10,. GetColor ?y 
GetMem( Grimagel3], ImageSize( 0, O, 20, 20 ) ); 
GetImage( 0, 0, 20, 20, Grimagel[31%* ); 
PutImage( 0, O, grimage[31*, XOrPut ); 
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The box image is the simplest of the four, using the Bar3D function to create a 
small cube. 


t= BOR: 
if MaxColors > 4 then SetColor( 13 ); 
paraet. 0,10, 10,215, 55 Tree )3 
GetMem(€ Grimage[4], ImageSize( 0, O, 20, 20 ) 2 
GetImage( 0, 0, 20, 20, GrimageL[4]* ); 
PutImage(€ 0, O, Grimagel41%, XOrPut ); 
end; 


In each case, memory is allocated for the image using GetMem and ImageSize, 
then GetImage stores the screen image and PutImage uses the XOrPut option to 
erase the screen for the next drawing. 


The LineGraph Function 


The LineGraph function begins by testing the data to find the highest value that 
requires plotting (MaxVal) and the viewport (window) is set to provide a top 
margin to allow space for labels. 


procedure LineGraph; 

var 
width, height, left, top, 
i, J, WStep, vStep, vwSteps, 
bottom, x, y, MaxVal : integer; 
scale : real; 


begin 

width := GetMaxXx; 

height := GetMaxyY; 

Left := 03 

top := 0; 

MaxVal := Q; 

TOf: Feces Lig) 4 do ; 
Toe.) -e° 4 ¢o -20..do 


if AccountslCi,j] > MaxVal 
then MaxVal := AccountsLi,j]j; 
SetViewPort( left, topt5, 
Lefttwidth, toptheight+5, False ); 


Next, vertical and horizontal steps are set to fit with the current screen resolu- 
tion and with MaxVal. 


dec( width, 30); 
hStep width div 20; 
vSteps ¢ MaxVal div 25.) + (2; 
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vStep = height div vSteps,; 
bottom := vStep * vSteps, 
scale = vStep / 25; 


A series of vertical bars are drawn to mark off the years. 


if MaxColors > 4 then SetColor( GREEN 2 
1 ¢= QO; 
repeat 
Linet i, 1, i, vStep * vSteps 3 
inc( i, hStep * 4 ); 
until i > hStep * 32; 


Then a set of horizontal bars are drawn and labeled with amounts in steps of 
25 to complete the graph background grid. 


SetTextJustify( CenterText, CenterText : 

1 s= O; 

repeat 
i# MaxColors > 4 then SetColor( BLUE - 
Linet O, 1, h8Step * 20, 1 9,7 
if MaxColors > 4 then SetColor(€ WHITE 3 
x := hStep * 20 + 15; 
y := i; 
str( round( ¢€ bottom-i )/vStep }#25, Buffer >; 
OutTextXY( x, y, Buffer ); 
inc€ i, vStep ); 

until i > bottom; 


Each set of data is plotted separately, using a different color and line style. This 
plot begins by setting the CP relative to the first horizontal graph position 
(hStep/2+3) and the adjusted vertical position (bottom — scale*Accounts|[i,0]+8) 
and calling OutText to put a label on the screen. Then the CP is set to the actual first 
plot position. 


SetTextStyle( SansSerifFont, Horizbir, + 49 
SetTextJustify( LeftText, TopTtext ) i 
top fF c= 1 ta 6 Go 
begin 
SetLineStyle( i-1, 0, 1 ); 
if MaxColors > 4 then SetColor ¢ Se ee 
MoveTo( hStep div 2 + 3, 
bottom - trunc( scale*Accountsli,1] ) + 8 ); 
OutText( AccTypeslil ); 
MoveTo( hStep div 2, 
bottom - trunc( scale*AccountsLi,1] ) ); 
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The data plot begins with the appropriate image (symbol) centered on the plot 
position, then a line is drawn to the next graph position. 
When the loop is finished, a final symbol is added at the end plot position. 


TOP Sf te Tite: FO ‘de 
begin 
PutImage( Getx-10, GetY-10, 
GrimageCild*, XOrPut ); 
LineTo€ hStep div 2+ j * hStep, 
Bottom - trunc( Scale*Accountsli,j] ) ie 
end; 
PutImage( Getx-10, GetY-10, 
GrimageClil*, XOrPut ); 
end; 


If you would prefer a simpler display, instead of the PutImage functions, a three 
by three dot could also be used to show the plot position. 


Tor xX. S8.=9 te -4 do 
TOP? Y tee) to FT do 
PutPixel(€ hStep / 2 + x, 
bottom - scale*AccountsLli,Ol+y, 


GetColor )»: 
One final step is required to list the years against the graph display. 


if MaxColors > 4 then SetColor( White yes 
SetTextJustify( CenterText, CenterText 72 
SetTextStyle( DefaultFont, NOCD TPL: 2): 
Tor) 2eCT t6 5 dé 
begin 

x := 1 * hStep * 4 = hStep * ef 

y == vStep div 2; 

str(€ YearsCil, Buffer ); 

OutTextXxXY( x, y, Buffer ); 
end; 
end; 


Summary 


Business graphs are one of the most important graphics applications if only because 
boardroom executives from the old-school can appreciate the value of financial 
graphs, even if only to use the graphic presentation to impress others. Cynicism 
aside, it is simply a recognized fact that business applications are judged, at least 
in part, by the quality and variety of their graphics. In real-world programming, 
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presentation and impressions are important if only to grab the customer’s initial 
attention. 

So, be as cynical as you like but don’t let cynicism get in the way of success— 
here are the tools for making an impression, use them and have fun. 


ee 
{ GraphALl.PAS } 
{ multiple graph demos’ } 
| eee ee 

uses GRAPH, CRT; 

type 

STR5 = stringtl 54; 
const 


Accounts : arrayl1..4,1..9] of integer = 
CSG SORT sl 1385 Bon See Thy 29, 485 4%e Se > 
C 9968, (22, 47, 30, €2y 18, @65 -B35.21 > 
C4969, 144,65, Sf, 146° T4% 4 Re. fs ar ee 
¢ 1990,| 100, 60, 70, 12, 18, Sy 17> Veo.2 Fy 
Acctypes : arrayl1..94 of STR5 = 
i. .3 i “Motor”, 'Acsry’, 'Reprs', 'Govmt', 
‘tease’, ‘Tires', ‘Paint’, 'a1$e" 27 
var 
GraphDriver, GraphMode, MaxColors, ErrorCode, 
XWidth, YHeight, ZDepth, 


XAxis, YAxis, ZAXiS, 
XOrg, YOrg, 
MaxX, MaxY : integer, 


Scale, AspR : real, 


procedure Initialize; 
var { initialize graphics system and report errors } 
xasp, yasp : word; 
begin 
GraphDriver := DETECT, 
InitGraph( GraphDriver, GraphMode, '\TP\BGI' ); 
ErrorCode := GraphResult, 
if ErrorCode <> grOk then 
begin 
writeln(' Graphics System Error: ie 
GraphErrorMsg( ErrorCode ae 
helen Tt 2s 
end; 
MaxColors := GetMaxColor + 1; 
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GetAspectRatio(€ xasp, yasp d's 
AspR := xasp / yasp; 


MaxX := GetMaxX; 
MaxY := GetMaxyY; 
end; 


procedure Pause; 

var 
Che: ener: 

begin 
while KeyPressed do Ch := ReadKey; 
Ch := ReadKey; 

end; 


function I2SC( Value : integer ): string; 
var 
Buffer : string(l10]; 
begin 
str€ Value, Buffer ); 
I2S := Buffer; 
end; 


(HHKKKKKKKKKKKKREEK PIE GRAPH Hk ek Rk RR KR kk eK 


procedure PieGraph( DataSet, x, y : integer } 
const 
BlankLine = $0000; 
var 
1p Ra Bs HJust, VJust, 
Total, Captoter : integer; 
ArcRec : ArcCoordstype; 
begin 
m t= 1353 
Total := Q; 
TORS Fee te: 9 ode 
inc€ Total, AccountsL Detaset, F 2 3; 
r 3:= Total div 4; 
SetLineStyle( UserBitLn, BlankLine, NormWidth ae 
SOCFILIStylet 0, O >); 
PIOGt 1 G60: *,): ¥,. Mm, nt P+710.)% 
{ one degree minimum Width required } 
GetArcCoords( ArcRec ); 
if MaxColors > 4 then Seitd lark White ); 
SetTextStyle( SansSerifFont, HorizDir, 2 ) Be 
SetTextJustify( RightText, Sottoutext d» 
OutTextXY(€ ArcRec.xEnd, ArcRec.yEnd, 
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T26( Accountst DataSet, 1° 2.2497 


SetTextStyle( DefaultFont, HorizDir, ‘er 


if MaxColors > 4 then SetColor (¢ EGAYeLlLlow ); 
e 2:2 OO; 
€.42 Oy 
for 7 3:2 @ to 9 de 
begin 
Sethi Listytet TeTty 1-127 
if MaxColors > 4 then SetColor( White ); 
SetLineStyle( SolidLn, QO, NormWidth ); 
inct t», round( 360 * « AccountsL rere oe 
i Perel > * O25 2 FF 
1¢ ¢ se 360 then: €) t= 360; 
et 4 2°9°) ond © t .< 360 2 then t 425 360; 
Pi eblicét xX. ¥u Be: teh. 7 
SetLineStyle( UserBitLn, BlankLine, NormWidth ); 
SetPi UL Letyviet Gy 8.3 
CapColor := it8,; 
1 CapColoar > 15 <heon CapColor := 7; 
if MaxColors > 4 then SetColor ( CapColor 2}; 
m := round( (t-s) /2 + 8 );7 
PieSlicel Ny _¥o Me WET) FHS 77 
{ must have a minimum Width of one degree } 
GetArcCoords( ArcRec ); 
af ArcRec.xEnd > x then HJust := LeftText 
else HJust := RightText, 
if ArcRec.yEnd > y then VJust == TopText 
else VJust := BottomText, 
SetTextJustify( HJust, VJust r 
OutTextXY€ ArcRec.xEnd, ArcRec.yEnd, 
AcctypesLlCild ); 
s := t; 
end; 


end; 


1 


begin 


procedure DrawPieGraphs; 


integer; 


ClearDevice; 

GraphDefaults; 

Rectangle( O, O, MaxX, MaxyY pe 

PieGraph( 1, GetMaxX div 4, GetMaxY div 4 ); 
PieGraph( 2, GetMaxX div 4, 3*GetMaxY div 4 ); 
PieGraph( 3, 3*GetMaxX div a GetMaxY div 4 ); 
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end; 


PieGraph( 4, 3*GetMaxX div 4, 3*GetMaxY div 4 ais 


(kkk KKKKKKKKKKKKKKEEK BAR GRAPH 1k kk kK RR RR RK kk RK 


procedure BarGraph; 
var 
Vie Shy Reo Ms WStéen, vStep, Top, Bottom, 
BarHeight, Width, Height, Left : integer; 
begin 
Width := Maxx; 
Height := MaxyY; 
Left := 0; 
Top. 2:=.0% 
ClearDevice; 
GraphDefaults; 


SetViewPort( Left, Topt5, 
Left+Width, ToptHeight+5, False 
dec(€ Width, 30 ); 
hStep Width div 32; 
vStep Height div 6; 
Bottom := vStep * 6; 
if MaxColors > 4 then SetColor( GREEN )2 


1: 203 

repeat 
Linet 3, 0, 4, ( vStep* 6 ys 
nek’ TT, HStep * 44) > 

UnELE FF hStep * 32; 

if MaxColors > 4 then SetColor( CYAN s 

1. 3m G2 

repeat 
Linet- 0, i, WSten * 32,4 Ye 
TRet: 45 Viton): 

until i > Bottom; 


dec(€ Bottom ); 
if MaxColors > 4 then SetColor( WHITE 14 


SetTextStyle( DefaultFont, ROP TZO Tr. 3 1.):2 
SetTextJustify( CenterText, CenterText pie 
TOP OF Pere to 6 doe 


begin 
Kise WS tep. .* 32 6 F352 
y t= t>* vStep; 


de 
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Out Texexye xo we  Reee 750 - 7 ee Po ag 


end; 
for i ¢= 2 to 9 do 
begin 
for j := 1 to 4 do 
begin 
BarHeight := Bottom - 
round( AccountsCjJCild * vStep / pe eg 
if MaxColors > 4 then SetColor¢ 7#1 0-39 
if MaxColors > 4 
then SetFillStyle( i-1, jt9 ) 
else SetFillStyle( i-1, MaxColors-1 ); 
Bar3D( Ci-2)*hStep*4 + (j-1)*hStepte, 
BarHeight, 
(i1-2)*hStep*4 + (j-1)*hStepthStep-2, 
Bottom, 0, False ); 
end; 


34 MaxColors > 4 then SetColor WHITE ); 
OutTextXxyY ¢ (i1-1)*hStep*4-hStep*2, 5, 
AcctypesLil ); 

end; 

x == MaxX div 3; 

y := MaxY div 4; 

SetTextStyle( SansSerifFont, HorizDir, 4 ); 

for i := 1 to 4 do 

begin 
if MaxColors > 4 then SetColor( itl ); 
OutTextXY( x, y, I12s¢ Accountst i, 11) ); 
inc( x , TextWidth(C' r? ‘2S 

end; 

end; 


(kkkkkRRKKKKKR MULTIPLE BAR GRAPHS kk KKK KK KK KR KR RY 


procedure MultiBarGraph( DataSet, Left, Top : integer ); 
var 

Width, Height, i, hStep, vStep, 

Bottom, xX, y : integer, 

Scale : real; 
begin 

Width = MaxX div 2; 

Height := MaxY div 2 - 5 Be 

SetViewPort( Left, Topt5, 

Left+tWidth, ToptHeightt5, False ); 
dec( Width, 30 ); 
hStep := Width div 8; 
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vStep Height div 6; 

Bottom := vStep * 6; 

Scale := vStep / 25; 

if MaxColors > 4 then SetColor GREEN): 


for 7 se 0 to 8 de 
Linet 4 * hStep, 0, 1 * hStep, vStep * 6 ); 
if MaxColors > 4 then SetColor ¢ CYAN: Qs 
1: £3.05 
repeat 
Linet 0, 1, hStep * es Sloe BS 
THEN 4) NS ten) 3 
until i > Bottom; 


if MaxColors > 4 then SetColor WHITE ); 
SetTextStyle( DefaultFont, HOrTvEDin,g 1) 
SetTextJustify( CenterText, CenterText ye 
Tor: 1: 88:0 to 46 do 
begin 
X 38 Mstep * 8 + 153 
Yo se Tw Ve taep : 
CUOtTONERT CX, ¥, TESC 180 4 ee 4 : 
end; 
SetTextStyle( DefaultFont, VertDir, 1 )s 
SetTextJustify( CenterText, TopText ys 
TOR (18S te Bb ds 
begin 
if MaxColors > 4 
then SetFillStyle€ i, i+7 ) 
else SetFillStyle(¢ i+1, MaxColors-1 ); 
Bare ft =. 4. >) © HSten + ay 
Bottom - 
round( Scale*AccountsCDataSet,i+11]-1 Ji 
1 * hStep - 2, 
Bottom-1 ); 
OutTextxXY(€ (i-1)*hStep + NStep div.2,. 5, 
AcctypesLit1] ); 
end; 
SetTextStyle( SansSerifFont, ROrreeT rh, 2): 
SetTextJustify( CenterText, BottomText i. 
Xx 3:5 Width div 2; 
yY 2: WeTght div 2 - 4; 
OutTextxY( x, y, 12S( Accounts Dav Oset yy TD ey 
end; 


procedure DrawMultiGraphs; 


begin 
ClearDevice; 
GraphDefaults; 
MultiBarGraph ( 
MultiBarGraph( 
MultiBarGraph ( 
MultiBarGraph( 

end; 
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proceaqure FICEPLane¢ 215 Vi wee lee KS» YS, Ahy VE 


FStyte, FColor : integer ); 


var 
Polygon : array[£1..10] of integer; 

begin 
POoLYygonL 1d := XT: PolygonL2] = Y1; 
Polygonl3] := X2; PolygonL[4] = Y¢2 
Polygon[l5J] := X3; Polygonlé6] = YS; 
Polygonl7J] := X4; Polygonl8] = Y4; 
Polygonl9] := Polygonl[1]; 
Polygon[L10]:= PolygonL2]; 
if MaxColors < 4 then FColor := MaxColors - 1; 


SetFillStyle( 
end; 


procedure GraphFi 
var 

i : integer; 
begin 


FStyle, Fieters 3: 


FILiPolyt 5, Polygen 33 


eld; 


if MaxColors > 4 then 


begin 
FillPlane(¢ 


FillPlane( 


A0rg, YOre, 

XOrg+XWidth, YOrg, 
XOrg+XWidth, YOrg-YHeight, 
XOrg, YOrg-YHeight, 
SolidFill, LIGHTBLUE ); 


AOrg, YOrg, 
XOrg-round(ZDepth/AspR), 
YOrg+ZDepth, 
XOrg-round(ZDepth/AspR), 
YOrg+ZDepth-YHeight, 
XOrg, YOrg-YHeight, 
SoltdFilt, LIGHTRED .)3 
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FillLPlLane( XOrg, YOrg, XOrgt+XWidth, YOrg, 
XOrg+XWidth-round(ZDepth/AspR), 
YOrgtZDepth, 
XOrg-round(ZDepth/AspR), 
YOrg+ZDepth, 

SoltdFitt, YELLOW. 27; 


end; 

Line( XOrg, YOrg, £ maior X-axis. i 
XOrg+XWidth, YOrg ); 

Line -xOre,: Tord, we yer  ¥: exis 3 
XOrg, YOrg-YHeight ); 

Linet( xXOrg, YOrg, {major Z axis } 


XOrg-round(ZDepth/AspR), YOrgtZDepth i: 


if MaxColors > 4 then SetColor(GREEN); 
{°X axis: position tines :3} 

ij 22 XOrg + XAX18; 
repeat 

Linet: 4, YOrg, i, YOrgrYHetght J); 

Ane: ia YOrs, 

i-round(ZDepth/AspR), YOrgtZDepth os 

Het Fe RATS. 22 

until i > XOrg + XWidth; 


if MaxColors > 4 then SetColor( CYAN ); 
{ Y-axis sosittion: lines) 

ij := YOrg - YAxis; 
repeat 

Linet xXOrg, ty XOrgtXWidth, 1 2; 

Linet AOra, T> 

XOrg-round(ZDepth/AspR), i+ZDepth ); 

Geet TAK TS ...27 3 

until i < YOrg - YHeight; 


if MaxColors > 4 then SetColor( RED ); 
C-Zvexis position tines > 
i: 32: ZANTE? 
repeat 
Line(€ XOrg-round(i/AspR), YOrgti, 
XOrg-round(i/AspR)+XWidth, YOrgti ); 
Line(€ XOrg-round(i/AspR), YOrgti, 
XOrg-round(i/AspR), YOrg-YHeightti ); 
$ASC Mg PARTS. 2S 
UNnttTr Pee Zoe otney 
end; 
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procedure ShowLabels; 
var 
ly jv ky ly wt 4hteger: 
begin 
SetTextJustify( CenterText, CenterText ); 
j := XOrg + XWidth + TS. 
L := XOrg - round( ZDepth / AspR ) - 15; 


for 1 s= 1 to 6 do 

begin 
kK := YOrg - i * YAxts?: 
OutTextxYt j, k, 22$0-t425:.).):; 
ms= YOrg + ZDepth - i * YAxis; 
OutTextxyt ts MW, ERSC Tr Ree 7: 

end; 


if MaxColors > 4 then SetColor( LightBlue ); 
j := XOrg + 25; 

Ll s:= j - round( ZDepth /-AsoR ); 

m := YOrg + ZDepth + 8; 

k := YOrg - YHeight - 8; 


for 71 := 1 to 8 do 
begin 
OutTextxY ¢ 


j kK, AGCtvyoest i414 2s 
CutTaxtxky< m, 

) 

) 


Acectypestt+1.J. ); 


=) 


ext 3. 438 
mies to088 
end; 


= 


= 


if MaxColors > 4 then SetColor( LightGreen ); 
for 41 := 0 to 3 do 


begin 
j = XOrg - 
round€ € i*ZAxis + ZAxieZ#2 ) / AsgpR } * 2; 
m<:= YOrg + round( i*ZAxis + ZAxts/2°)3 
k := m —- YHeight; 
lL s:= j + XWidth; 


SetTextJustify( LeftText, TopText ); 
OutTextazyt Ll, m, T28% Acecountec 1677.14.43 7%.) 
SetTextJustify(€ RightText, BottomText ); 
OutTextxy( 3, Ky, T2S Accounts tete 1-3 2) 33 
end; 
end; 


procedure AddBar( Left, Bottom, Height, 
Color, Covered: Integer >; 
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var 
Top, Right 
begin 
BarWidth 
BarDepth 


, BarWidth, BarDepth : integer; 


XAxis div 2; 
ZANTE div 2; 


if MaxColors < 4 then 


begin 
Color’ 
Color2 
end; 


= MaxColors - 1 
‘= MaxColors - 1 


7 
* 
7 


Set FiltisStyiet: tater), Colort 2; 


Left := 
round (¢ 


Bottom := 

round ¢ 
Right := 
Top := 


Barseut Lett, Tea, Rignt, Boettot, U, Favee 


FillLPlLane( 


FillPlane( 


end; 


Ora #0 Left * KAX1$.2)* 

COO @e¢ezon- + € 0.33) Aes 1 
* CAKVS:2::/ AspR 3}; 

+Or¢g + 

C ‘Bottom + 0.70.) 4 ceAnis: 2:3 
Left + BarWidth; 

Bottom —- Height; 


RIGHT, TEbs 

Righttround( BarDepth/AspR ), 
Top-BarDepth, 

Right+round( BarDepth/AspR ), 
Bottom-BarDepth, 

Right, Bottom, 

CloseDotRtitty- Calor t:is 

Left, Top, RIGHT: TOR, 
Rightt+tround( BarDepth/AspR ), 
Top-BarDepth, 

Left +tround( BarDepth/AspR ), 
Top-BarDepth, 

SOLTAETLC, CatorZsd 22 


procedure ShowAccounts; 


var 


i: integer; 


begin 


XAxis ) 


3 


if MaxColors > 4 then SetColor( EGAYellow ); 
for 728.2: to Fda 


begin 
AddBar (¢ 


AddBar ¢ 


i-2, 0, round< Accounts(£1,11] * Scale ), 


LightCyan, Cyan); 


i-2, 1, ‘round ( Accountst2,T] :* Scate ), 





AddBar ¢ 


AddBar ( 


end; 
end; 
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LightRed, Red ); 


i-2, 2, round( Accountsl3,i] * Scale ), 


LightBlue, Blue ); 


i-2, 3, round( Accountsl4,i] * Scale ), 


LightGreen, Green ); 


procedure ThreeDGraph; 


var 


X, y 
begin 


integer; 


ClearDevice; 


XWidth 


YHeight 


ZDepth 


8 * XAxis; 
6 * YAxis; 
4 * ZAxis; 


setTextJustify( LeftText, TopText ); 
SetColor( GetMaxColor ); 

x 3g TO2 
OutTextXxYC( x, 
GraphField; 
ShowLabels; 
ShowAccounts; 


Pause; 
end; 


y 35 


10; 
Yo “Dhete cee owe Dea ZARIs ) 93 


procedure Graphs3D; 


begin 


ClearDevice; 


GraphDefaults; 


XAxXis 
YAxis 
ZAxis 
XOrg 
YOrg 
Scale 
ZAXxis 
repeat 


MaxX 
MaxyY 
10; 

MaxX 
MaxyY 


Give t33 
atv 14; 


div 3; 
Giv <3; 


YAxte f €5% 


Loe 


ThreeDGraph; 


ines ZAxXis; 


10 aF 


until YOrgt4*ZAxis > MaxyY; 


end; 


488 USING TURBO PASCAL 6.0 


(KKK KKKKKAEKKKKEEKE MAIN GRAPH RRR RK RK EK RK KH KK RK KY} 


begin 

Initieti2¢s { set graphics mode 

DrawPieGraphs; 

Pause; 

BarGraph; 

Pause; 

DrawMultiGraphs; 

Pause; 

Graphs3D; 

CloseGraph; { restore text mode 
end. 


{seseeeseeeseesrezezec=} 
{ LineGraf.PAS } 
{ sample Line graph } 
{seseeeseserssseesseese==} 

uses GRAPH, CRT; 

type 

STR5. 3 striTnAglél: 
const 


Accounts: : arravet.<¢6,.14 203 of Anteger = 
C06. 999, tet WSs RO TA Tae Ree, Teeter heey 
124) VO TER SG TOF ats tees VO gp ey Tee o> 
Cee Seg 400) AOS TVS face tele TAB ae, eu, 
168. T72, 167; 153, TSS > TOS 160 153, ey ee 2, 
CT oe Bes Dy a pe eee ged a ee a SS Re 
a. aa CUe hey OST oa eek eae Chey CORO ag 
Cea es POs ONE ae yt Oe Sk pe ee i i RON 
ao £Oe. Reel eS ep Ce 2 ee CO eee seep ee 2h? 
Years : array(l1..5] of integer = 
( 4966; 1987, 71966, 19869, T1990); 
Acctypes.: errayet..44:..07: STRS = 
C Gente! ss:  "UAVELe! 2 Stree"). “Netetr 23 
var 
GraphDriver, GraphMode, 
MaxColors, ErrorCode : integer; 
Grimage : array(l1..4] of pointer; 
Buffer 2: STRS 3 


procedure Initialize; 
begin 
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GraphDriver := DETECT; 

InitGraph(€ GraphDriver, GraphMode, '\TP\BGI' 

ErrorCode := GraphResult; 

if ErrorCode <> grOk then 

begin 
writeln(' Graphics System Error: ', 

GraphErrorMsg( ErrorCode ) ); 

neLtt-1 3 

end; 

MaxColors := GetMaxColor + 1; 

end; 


procedure Pause; 
var 
CN 2 Caers 
begin 
while KeyPressed do Ch := ReadKey; 
Ch := ReadKey; 
end; 


procedure LineGraph; 

var 
WIGTH, Hetgut, Lett, too; 
1, jp, hStep, vStep, vSteps, 
bottom, x, y, MaxVal : integer; 
scale : real; 


begin 
width := GetMaxXx; 
height := GetMaxyY; 
Left := QO; 
top := 0; 
MaxVal := OQ; 


TOP. 41: te"): #0 6 ds 
for j} 82-41 to 20: .¢0e 
if Accountsti, to > MaxVal 
then MaxVal := Accountsli,jd; 


SetViewPort( left, top+5, 
Lefttwidth, toptheight+t+5, False 
geet width, 30 2 


hStep = width div 20; 

vSteps := ( MaxVal div 25 ) + 2; 
vStep = height div vSteps; 
bottom := vStep * vSteps; 

scale = vsteno / 23: 


if MaxColors > 4 then SetColor( GREEN ); 


); 
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1 ee ea 
repeat 
LitneG 4,1, 1, vStep.* vsteps >; 
THeK ARS ten F427 
until 4 > AStep:* 32; 
SetTextJustify( CenterText, CenterText ); 


1 8 Os 

repeat 
if MaxColors > 4 then SetColor( BLUE ); 
Ligeti. 4, AStep * 20, ‘toa 
1% MaxCotors > 4 then SetColor ( WHITE ); 
eye nStep * 20.4 157 
y 35 41> 
str( round( ( bottom-i )/vStep )*25, Buffer ); 
OutTextey( x, y, Butter 2% 
met 1, VSten >; 

untit > bottom: 


SetTextStyle( SansSerifFfont, Horizdir, 1 2; 
SetTextJustify( LeftText, TopText ); 
for. 3-28: F" to 4 Go 
begin 
Setiinestyle¢ i<t, Ge.1 Fe 
14: MaxCotors > 4 then SetCotort( i1+17 2; 
Rover oC AStep ‘div <2 .* 3; 
bottom - trunc(.scale*Accountsli,1] )» + 8 ); 
OutText( AcctypesLlidld ); 
MoveTo( hStep div 2, 


bottom - trunc( scale*Accountsli,1] ) ); 
{ Creates a 'dot' around the plot position } 
Cs EP RE eet eG Ta0 } 
Co -Fer. yy te =1..teo te do } 
{ PutPixel¢ hStep 7:20. 4x; } 
{ bottom - scale*Accountsli,Olty, } 
{ GetColor ); } 


TO 228-1. to: Tt? ae 
begin 
PutImage( GetxX-10, GetY-10, Grimagelild*%, XOrPut ); 
LineTot hStepn div: 2 + }.* HnStes, 
Bottom - trunc(€ Scale*Accountsli,jl] ) ); 


end; 
PutImage( GetXxX-10, GetY-10, GrimageLil*, XOrPut ); 
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end; 
if MaxColors > 4 then SetColor( White ); 
SetTextJustify(€ CenterText, CenterText ); 
setTextStyle(€ DefaultFont, HorizDir, 2 ); 
Tor 1 #2 4 to 5 do 
begin 
Xx := 1 * hStep * 4 = hStep * 2; 
y := vStep div 2; 
str(€ YearslLild, Buffer ); 
OutTextXY(€ x, y, Buffer ); 
end; 
end; 


procedure Create_Images; 
const 
Figure : array(l1..16] of integer = 
$ Ey Bye Wika “Soy #0 Tt, 108, 
iy Vy Top Fes Be 134 104 5 Fy 
var 
i: integer; 
begin 
{ wheel / gear } 
SetFillStyle( EmptyFill, O dD; 
if MaxColors > 4 then SetColor( 10 ); 
for i := 0 to 5 do 
PreSticet 10, 10, 1*60,. €1*60)4+60, 10 3, 
GetMem( Grimagel1], ImageSize( 0, 0, 20, 20 ) ); 
Getimage( 0, 0, 20, 20, Grimagel11* ); 
PutImage( 0, O, Grimagel11*%, XOrPut ); 


4 lightning belt } 
if MaxColors > 4 then SetColor( 11 ); 
FillLPoly(€ SizeOf(€ Figure ) div | 
C.2 * Sizeot( integer ) >), Figure ); 
GetMem(€ Grimagel[2], ImageSize( 0, 0, 20, 20 ) ); 
GetIimage( 0, 0, 20, 20, Grimage[21]% ); 
PutImage( 0, O, Grimagel2]*%, XOrPut ); 


4 oil drop 3 
if MaxColors > 4 then SetColor( 12 ); 
Are. 10, (10, . 105, 360, 6.33 
Eilipee< 8, 3, S00, 80s -. 82 3.23 
ELiLTpeet. “Sy 0, 0, 90, 16,343 
SOtFILIStylel SolidFrilti, Getcoler 3); 
FLOOGFILLC 70,10, Gett€olor 2}: 
GetMem(€ Grimagel3], ImageSize( 0, 0, 20, 20 ) ); 
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end; 


beg 
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GetImage( 0, 0, 20, 20, Grimagel351]* ); 
PutImage( 0, 0, grimagel[31%, XOrPut ); 


: {Por 2 
if MaxColors > 4 then SetColor( 13 ); 
Bars0t G.°40, 1035 73555 Tree? 
GetMem( Grimagel4], ImageSize( 0, 0, 20, 20 ) ); 
Getineget 0, 0, 20, 20, GrimegeleJ* 2; 
PutImage( 0, O, Grimage[4]%, XOrPut ); 


7 


in 

Initialize; 
Create_Images; 
LineGraph; 
Pause; 
CloseGraph; 


end. 





Chapter 27 


Colors and Color Selection 


This chapter is concerned primarily with colors and color selections in EGA/VGA 
modes and, secondarily, with CGA and Monochrome systems. 

This restriction is not intended as a put down of CGA or Monochrome video 
modes, but is simply a recognition of the fact that CGA systems have limited color 
capabilities and Monochrome systems have effectively none. 


Video Signal Cues 
On Monochrome systems, graphic video output is limited to two bits of information 


per pixel: a video on/off and an intensity bit (see Table 27-1). 


Table 27-1: System Video Attributes 
Bit # Monochrome Color RGBI Color EGA/VGA 


0 n/a Blue Primary Blue 

1 n/a Green Primary Green 

2 n/a Red Primary Red 

3 Video n/a Secondary Blue 
4 Intensity Intensity Secondary Green 
5 n/a n/a Secondary Red 


On CGA systems, the RGBI (Red, Green, Blue, and Intensity) color system is 
used with four bits of information per graphics pixel, but combinations are limited 
to four, predefined palettes of three colors plus background color (as shown in Table 
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27-3). The background color in each palette is BLACK by default, but can be selected 
from the entire range of 16 colors shown in Table 27-2. 


Table 27-2: CGA Color Values 


Lass Wg BE aso cath A lied Re EEE: ST ee Ee ELE OS ee eS 

Color Values 4-bit Binary Constant | 
dec hex Color Components Color Name 

0 0 0000 are Cae Black 

1 1 0001 ae Blue 

2 2 0010 ae oe Green 

3 3 0011 urs SB Cyan 

| 4 0100 ee Red 

5 i) 0101 ie uae © Magenta 

6 6 0110 ieee Brown 

7 7 0111 . RGB LightGray 

8 8 1000 eee DarkGray 

9 9 1001 ree LightBlue 

10 A 1010 ales Se LightGreen 

11 B 1011 I .GB LightCyan 

12 C2100 LR LightRed 

13 B+ 330) IR: 8 LightMagenta 

14 E 1110 IRG.., Yellow 

15 F 1111 IRGB White 


On EGA/VGA systems, the RrGgBb color system uses six bits of information 
per pixel for a total of 64 colors/hues. The default colors for this palette are shown 
in Table 27-4. 


CGA Colors 


For CGA systems, 16 possible colors are supported, as shown in Table 27-2. In text 
modes, any of these colors can be selected as foreground color, though only the first 
eight colors are valid as background colors. 

Using Turbo Pascal graphics, the AT&T driver (modes ATT400C0..ATT400C3) 
and the MCGA driver (modes MCGACO..MCGAC3) operate in the same fashion 
as CGA modes, CGACO..CGAC3. Similarly, color operation in the CGAHI mode is 
duplicated by the MCGAMED, MCGAHIL, ATT400MED, and ATT400HI modes. 

As shown in Table 27-2, each color is defined by four register bits controlling 
the red, green, and blue hues and an intensity control. Each hue (color gun) has two 
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settings: low and high intensity. When the Intensity bit is TRUE (ON), all color guns 
are set high. If Intensity is FALSE, all color guns respond as low. 


Table 27-3: CGA Color Palette 


Color Values 4-bit Binary 
dec hex Color Components 

PALETTE NUMBER 0 (CGACO) 

0 0 0000 err 

1 A 1010 LG. 

2 B 1100 LR 

3 C 1110 IRG. 

PALETTE NUMBER 1 (CGAC1) 

0 0 0000 Shas 

1 B 1011 I.GB 

2 D 1101 Lee 

3 F 1111 IRGB 

PALETTE NUMBER 2 (CGAC2) 

0 0 0000 eKeS 

1 2 0010 mens 

2 4 0100 oy 

3 6 0110 : ae Rs 

PALETTE NUMBER 3 (CGAC3) 

0 0 0000 ey 

1 3 0011 JG 

4 5 0101 Rb 

3 7 O11] RGB 


Constant / 
Color Name 


Black 
LightGreen 
LightRed 
Yellow 


Black 
LightCyan 
LightMagenta 
White 


Black 
Green 
Red 
Brown 


Black 
Cyan 
Magenta 
LightGray 


Blue is generated by turning on the blue gun at low intensity; LightBlue also 
turns on the blue gun, but because of the Intensity flag, is turned on high and 
produces a brighter color. In the same fashion, turning on both the green and blue 
guns produces Cyan; adding the Intensity signal produces LightCyan. 

As a minor oddity, notice that enabling the Intensity signal alone (with the red, 
green, and blue guns off), still produces a response from all three of the color guns, 
though their output is very low, and the result is DarkGray. You might consider this 


a bug that has been turned into a feature. 
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In graphics modes, the CGA system supports multiple colors only in the four 
low resolution, 320x200 pixel modes (CO, C1, C2, and C3). Each of these modes 
selects one of the predefined 4-color palettes shown in Table 27-3. 

By default, the background color in each palette is Black, but may be changed 
to any of the 16 CGA colors (see Table 27-2) using the SetBkColor function. The 
SetPalette and SetAllPalette functions—used in EGA/VGA modes to change pal- 
ette colors—are not applicable in CGA modes. There is, however, one exception: 
the function SetPalette(PaletteIndex, color) can be used with a PaletteIndex of zero 
(background), as an alternative to the SetBkColor function. 

The CGA colors Blue (value 1), DarkGray (value 8), and LightBlue (value 9) do 
not appear in any of the defined palettes. These can, of course, be used as back- 
ground colors. 


CGA High Resolution 


In any of the high resolution modes (CGAHi, MCGAMed, or ATT400Med at 
640x200 pixels; MCGAHi at 640x480 pixels or ATT400Hi at 640x400 pixels), two 
colors are supported: a black background and a color foreground. The foreground 
color is selected from the 16 CGA colors using the SetBkColor function. No, this is 
not an error. Due to a quirk in the CGA hardware, the SetBkColor function is used 
to select the CGAHi foreground color. The background color remains black. All 
pixels with a value of 1 are displayed in the foreground color, pixels with a value 
of 0 remain black. 


The IBM8514 and VGA Video Adapters 


At the other extreme, the highest color resolution is provided by the IBM-8514 video 
card and the IBM8514 mode or by the VGA video card using the VGA256.BGI 
driver, both of which are supported by the SetRGBPalette function. 

The SetRGBPalette function allows custom color definition for a palette of 256 
colors. To maintain compatibility with other video adapters, however, the first 16 
palette entries are predefined by the .BGI drivers to correspond to the default 
EGA/VGA color palette entries. 

All 256 palette entries (numbered 0..255) can be defined individually by three 
integer color arguments: red, green, and blue. While the arguments passed to the 
SetRGBPalette function are integer values, only the six most-significant bits of the 
lower (LSB) byte are actually used to set the palette color value (values from 0 to 
252 in steps of four, i.e., arguments of 252, 253, 254, and 255 are treated identically 
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since the six most-significant bits are the same and only the two least-significant 
bits differ). 


EGA/VGA Color 


EGA/VGA video modes offer a palette of 16 colors selected from a spectrum of 64 
possible hues. In actual fact, VGA systems are capable of wider color ranges, having 
256 color registers and 256 possible hues. When using Turbo Pascal procedures, 
they are effectively limited to the EGA color range, though they still support the 
higher resolutions. 

For the present, the topic is restricted to color handling within the capabilities 
of Turbo Pascal and restricted to the EGA color range of 64 hues. 

The EGA/VGA modes also begin with a default palette of 16 hues. Unlike the 
CGA color system using 4-bit colors, each EGA/VGA color is defined by a 6-bit 
value. This is commonly called an RrGgBb color system. 

The RrGgBb color system provides two flags (and two signals) for each of the 
three color guns: a primary Red and secondary red, a primary Blue and secondary 
blue, and a primary Green and secondary green as shown in Table 27-4. (By custom, 
the primary color is capitalized and the secondary is in lowercase.) 


Table 27-4: EGA/VGA Default Palette 





Palette Default Color Value Color Constants / 
Index hex 6-bit Binary Components — Color Names 

0) 0 O00 CO rw EGABlack 

1 1 000 O01 tant tee EGABlue 

2 2 000 010 ees, ae EGAGreen 

3 3 000 O11 i ae EGACyan 

4 4 000 100 Tore ape EGARed 

3 5 000 101 a eee EGAMagenta 

6 14 010 100 oe ee EGABrown 

7 7 000 111 oR. EGALightGray 
8 38 111 000 ae EGADarkGray 
9 39 111 001 rgb..B EGALightBlue 
A 3A iti. 010 rgb.G. EGALightGreen 
B 3B 171 011 rgb.G B EGALightCyan 
C 3C 111 100 rgb.” EGALightRed 
D 3D 111 101 rgbR .B EGALightMagenta 
E 3E 111 110 rgok G-. EGAYellow 

F oF cis Aa! A rgbR GB EGAWhite 
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It may help to think of the RrGgBb system as analogous to the RBGI system, 
except that the secondary colors act as individual intensity flags for each of the 
primary color guns. 

Just as DarkGray was created in CGA by turning on the Intensity flag but 
leaving off all of the color flags, EGADarkGray turns on the rgb (intensity) flags 
while leaving the RGB (primary) color guns turned off. On the other hand, where 
the CGA system created Brown by mixing the Red and Green guns, EGABrown is 
created by mixing the Red color gun with the green intensity flag—mixing Red with 
a very low Green produces a deep Brown. 

Aside from the EGABrown, the default palette colors for EGA/VGA are the 
same as the CGA colors except that three intensity signals (rgb) are used in place 
of a single intensity flag—gang-controlling all three color guns. 


A Wider Range of Hues 


One of the advantages of EGA/VGA, in addition to being able to use 16 colors in 
high resolution modes, is being able to select your palette from 64 separate hues. 

To be frank, some of these 64 colors are not particularly appealing and the 
precise tone of a particular hue is subject to the color balance adjustments on the 
monitor used, but beauty is, as always, in the eye and monitor of the beholder. For 
an example of the range of color, Table 27-5 shows 11 varieties of yellow, ranging 
froma color value of 06, which matches the CGA Brown to a color value of 62, which 
corresponds to EGAYellow. 

Looking at the color components shown in Table 27-5, you will notice all of the 
yellows include Green and, with two exceptions, blend Red. In one case, color value 
18, is actually high intensity Green, but depending on the surrounding colors and 
background, this may be recognized as either Yellow, Green, or Chartreuse. The 
precise recognition and label applied to any color is largely a matter of subjective 
perception. 


Manipulating Color and Hue 


Inthe EGA/VGAcolor system, specific color values can be created by manipulating 
the combinations of primary and secondary flags for each color gun. Each of the 
three color guns has four settings: completely off, low intensity (color off, intensity 
on), normal (color on, intensity off), and high (color on, intensity on)—for a total of 
43 or 64 colors. 
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If you need to manipulate colors directly, these bit-values can be set directly to 
build a specific color value, then you can assign the created value to the EGA/VGA 
palette. 


Table 27-5: EGA Yellows 
Palette Default Color Value Color 








Index hex 6-bit Binary | Components 
06 06h 000 110 Meroe: a oF 
14 OEh O01 110 vei Oas. Ms. 
18 12h 010 010 7 
22 16h 010 110 ERG. 
26 1Ah 011 010 eelG 
30 1Eh 011 110 _gbR G. 
38 26h 100 +110 eee es 
46 2Eh 101 +110 Yr. ORIG. 
54 36h 110 110 re RG: 
55 37h 110 111 rg.R GB 
62 3Eh 111 110 rgbR G. 


For example, suppose that you need three pure greens. Bit 1 controls the Green 
color gun (bit 0 at the right is blue) and bit 4 is the Green intensity flag, so the three 
pure greens would be 16 (010 000 or .g. .. .), 2 (000 010 or... .G.), and 18 (010 010 
or .g. .G.), in order of intensity. 

The first green (color value 16) is a dark green, appearing as khaki against some 
backgrounds. The second (color value 2) is a pure green and corresponds to 
EGAGreen, while the third green (color value 18) is a bright or chartreuse green 
and, depending on surroundings, appears almost yellow (and, if you noticed, is 
also included in the yellows in Table 27-5). 

But there is another green that does not appear among these possibilities. This 
fourth green is EGALightGreen, color value 58 (111 010 or rgb .G.). In this case, the 
rgb produces DarkGray (which, since we’re working with light emission and not 
color absorption /reflection, is also soft white). The dark gray is added to the Green 
color gun for a lighter green without becoming chartreuse. 

To show some of these relationships and to provide a convenient method of 
examining the variety of possible colors, two demo programs, COLCUBE.C and 
COLORS.C, are provided. 
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Please note that both of these demo programs will operate only on EGA/VGA 
capable systems. No provision has been made to adapt them for CGA systems; they 
are for high resolution color systems only. 


The Color Relations Cube 


The COLCUBE.C program uses the default color palette to create a doubled cube 
showing the relationships between primary and secondary colors. 

The physical spectrum, as seen in the rainbow or displayed by a prism, begins 
with Red and proceeds to Orange, Yellow, Green, Blue, and ends with Violet. To 
create our computer color spectrum, we have only the Red, Green, and Blue colors 
to work with. These three primary colors are, however, the three that the eye best 
perceives and by combining these as light, the eye perceives colors that are not 
actually present. 

In the case of a T.V. signal, these same three colors are used to generate 
everything from subtle ranges of flesh tones to the intense flashing headlines 
favored by automobile dealers on late-night movie ads. The T.V., using analog 
signals, is able to offer finer gradations and combinations of primary colors than 
the computer which, in EGA/VGA mode, is limited to four values. 

Notice that the figure created by COLCUBE.C (see Figure 27-1) has four main 
axes: red, green, blue, and white (or intensity). The human retina has three types of 
color receptors believed to correspond to the three primary colors. However, color 
perception is not limited to recognition of these three values, but also to the relative 
intensity of each and the balance between these. 

A balanced combination of all three colors is perceived as gray or white, 
depending on overall intensity. 

As mentioned, how colors are perceived is affected by other colors surrounding 
them and COLCUBE shows this effect by swapping the EGABlack and EGAWhite 
colors between palette color 0 (background) and palette color 15. 


The COLORS.PAS Demo 


The COLORS.PAS demo (see Figure 27-2) is simple overall, beginning with three 
global variables: radius, which sets the size for the display Circles; StepForward, 
which is used as a Boolean flag to determine whether the colors are incremented 
or decremented; and palette, which is the color palette structure. The structure type 
PaletteType is defined in the GRAPH unit. 
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Figure 27-1: Color Cube 








Enter <Q> to quit or any key to change colors 
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Figure 27-2: Colors Demo 
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forward step 
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reversed step 
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The program starts the graphics system using the same Initialize procedure as 
virtually all of the other programs in this book. 

The SetTextJustify and SetTextStyle procedures pick a font and text justification 
for the screen display, then write the appropriate messages to the screen. 


begin 
Initialize; 
radius := 30; 
StepForward := True; 
SetTextJustify( CenterText, CenterText ); 
SetTextStylel SansSeriffont, HorizDir, 1 J: 
Out Textxy¥¢ $20, 70; 

‘Enter <@> to quit or any «ey. to change colors' ).: 
OutTexiexy<: 100,250, ‘Enter <-s Tor*-)» 
OutTextXY( 100, 270, ‘reversed step' ); 
OCutrTextars 540,: 290, "Enter <€2 tor? 23 
OUTTOXEATC 5460, 270, "Torward step" .32 


Next, a special palette is created by the InitializeColors procedure. ShowColors 
writes 16 colored Circles in two rows, ColorWheel creates a pie chart with the same 
16 colors and, with the screen set up and drawn, StepColors is ready to show you 
through the 64 EGA/VGA color values. 


InitializeColors; 
ShowColors; 
ColorWheel; 
StepColors; 
CloseGraph; 

end. 


In the InitializeColors procedure, instead of using the default EGA/VGA 
palette colors, the palette entries are reset to color values 0..15, the first 16 colors. 
The SetPalette function assigns the unsigned integer values to the index elements 
in the palette structure. 


procedure InitializeColors; 


var 
1s integer: 
begin 
for T3233 0° to 15 do SetPalerttet s,s 3s 
end; 


The ShowColors procedure uses a single loop from 0 through 7 to draw 16 
Circles in two rows across the top portion of the screen. 


Chapter 27: Colors and Color Selection 503 





procedure ShowColors; 

var 
i: integer; 

begin 
GetPalette( palette ); 
for 1 = 0 to 7 Go 
begin 


The first row of Circles use the first eight palette colors: (palette.color[O]..pal- 
ette.color[7]). At the moment, these are also the first eight possible color values, but 
it is the palette entry value that is assigned to the screen pixels, not the color value 
contained by each palette entry. 


SetFillsStylet SotidFitl, 1 
Circle( 80*i+40, 50, radius ); 
FloodFill¢ 80*i+40, 50, GetColor ); 


The LabelColors function labels each colored Circle with the color value, not 
the palette item number. 


LabelColors( i ); 


The second row of Circles takes the second set of palette item assignments 
(palette.color[8]..palette.color[15)). 


SetFillStylet SeolidFiltt, i148 2; 
Circle( 80*i+40, 130, radius ); 
FloodFillL( 80*i1+40, 130, GetColor ); 
LabelColors( i+8 ); 
end; 
end; 
The LabelColors procedure is called with one argument specifying the palette 
entry number, then reads the value in palette.colorsli], and writes this value on the 
screen next to the colored Circle. While the rest of the screen will not be rewritten 
as colors change, the labels for the specific color values are rewritten each time a 
palette entry is changed. 


procedure LabelColors( i : integer ); 
var 
Buffer : string; 
begin 
str({ patette.colorsliji:2, bufter.2; 
if i> 7 then PrnNum( 80*i-600, 138+radius, buffer ) 
else PrnNum( 80*i+40, 58+radius, buffer ); 
end; 
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The ColorWheel function draws a second display in the form a of pie graph 


that has 16 slices filled with the 16 palette colors. 


procedure ColorWheel; 


var 
1 £ integer: 
begin 
for Te .0 to. Ts de 
begin 
SetFictstytet: Sotidhitt,  tse4:92 
Pileslicet: 320, 270, : trunet P22. $...3, 
tronct (C7et) 422.5-9. rediuse*s 
end; 
end; 


The last element in this demo is the StepColors procedure. 


procedure StepColors; 

var 
i, ThistCotoer : integer: 
Ch: +. chars 
Done : boolean; 


The Done variable is initialized as False, setting up a loop condition that will 
continue until Done becomes True. Until then, StepColors waits for a keyboard 


entry. 


An entry of “Q” or “q’” increments Done to allow an exit; an entry of “—” or “+” 


selects a direction for the colors to change. 


begin 

Done := False; 

while not Done do 

begin 
Ch := upcase( ReadKey ); 
Done: <2 Chee ‘Q's 
if Ch = '='" then StepForward 
if Ch = '+' then. StepFforward 
if not Done then 
begin 


False; 
True, 


Any keyboard entry that has not set the exit condition allows a second loop to 
increment or decrement the current palette color values. The loop steps through 
the 16 palette entries with ThisColor taking the value of each palette entry (pal- 
ette.colors|i]) in turn, then ThisColor is incremented or decremented as appropriate 
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with a final test to ensure that the resulting color value remains within the range 
0..63. 


for + 22 @ toe 15 do 
begin 
ThisColor :5 patette.coloreliti; 
if StepForward then inc(€ ThisColor ) 
else dec(€ ThisColor ); 
1f Thiscolor < OU then TATSCeOLor: t= 635; 
if ThisColor > 63 then ThisColor := OQ; 


Finally, SetPalette sets palette.colors[i] to the new color value, GetPalette 
updates the palette record, LabelColors updates the screen label, and a delay of 30 
milliseconds is executed before the loop continues. 


SetPalette( i, ThisColor ); 
GetPalette( palette ); 
LabelColors( i ); 
delay(30); 

end; 

When you run this demo, notice the screen colors change immediately when a 
new value is passed to SetPalette. If you would like to see a more pronounced 
demonstration of this effect, increase the value in delay(30); and add another delay 
before updating the color label on screen. 

Remember, the only action required to change a screen color is to assign a new 
value to the appropriate palette entry. This action will update the entire screen on 
the next sweep refresh cycle, regardless of window or viewport settings or which 
video page is currently active. 

This speed of change also allows other effects. For example, you could define 
several palettes as an array of type palette; for example, AltPalette : array[0..9] of 
PaletteType declares an array of 10 alternate palettes numbered 0..9 which can be 
used to save any array of colors. 


for 4 3s© @ to 16 Go 
palette.colorslild := 
AltPaletteC NewPalette J.colorslid; 


The loop can assign any of these as NewPalette to the active palette definition. 
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Summary 


Without going into tedious detail on the theories of color perception or the current 
fashions in colors and the technical aspects of how the color monitors and video 
cards function, you’ ve seen the essentials of how the several different video modes 
use color and what color instructions are accepted in different modes. 

In conclusion, here are a pair of colorful (pun intended) demo programs. Take 
them apart and play with them for a while. Try a few experiments and see what 
happens. Also, have a shot at building color values as previously described, these 
results can also be interesting. 

And, try using the shift operators (shl and shr) directly on the color values (not 
on the palette entry numbers). The effects are unusual. 

Take a bit of time, relax, play with the color assignments and see what happens. 
You may find something fascinating or useful, or both. 


{SHESrSerSerseseseseeeseserzesezzeze=zeez=} 
{ ColorCub.PAS } 
{ Color Chart for EGA Mode/Palettes } 
{sez Sseeesestsssssesetsestsestee2e22e2e=e2)}) 


uses GRAPH, CRT; 


const 
dx : arraylO..21] of integer 
dzx J erreayt0..2] of integer 
yFac : arrayt0..21 of integer 
zyFac: arraylO..2] of integer 
var 
dy, G2y¥<2-arreayvio..23 of integers 
GraphDriver, GraphMode, ErrorCode, 
MaxColors, Radius, VAdj, i : integer; 
Colors : boolean; 


C £ode. 2eus 240.2 
¢ vy “90, = Teo 2 
Cy 27 y S ) 
¢ ) 


procedure Initialize; 
begin 
GraphDriver := DETECT; 
InitGraph(€ GraphDriver, GraphMode, '\TP\BGI' ); 
ErrorCode := GraphResult; 
if ErrorCode <> grOk then 
begin 
writeln(" Graphics System Errors: *, 
GraphErrorMsg( ErrorCode ) ); 
Rete 3 2's 


end; 

end; 

procedure SetCircle( X1, Y1, 

begin 
SetFillStyleC SolidFill, 
SetLineStyle(€ SolidLtn, O, 
SetColor( EGAWhite ); 
Circle( dx€X1J¢*¢dzxCZtiJ, 
SetColor( EGABlack ); 
Circle dx€X1I3+e2xCZ14, 


Z1, 


Color 


¥ 


dyCY1J+dzyClZ11, 
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integer ); 


Coler-i2z 
1 23 


Radius 2; 


dvLY1I+d2yvyEiiid, 


Radius div 2 ); 


FloodFill¢ dxC€X1J+dzxCZ11+1, 
dyC¥Y1jJ*#dzy€Z1Ji+t, 


EGAWhite ); 


SetColor( EGALightGray ); 
end; 


procedure CLine€ X1, Y¥1, Z1, Xe, 
begin 
SetLineStytet Solidin, 0, wet 


LineC dxCX1J¢+dzxC€Z11, 
dx€X2J+dzxCZ21, 
end; 


procedure ColorCube; 

begin 
SetColor (¢ 
CLine( O, 
CLinget Ty 
CLIne< 1) 
CLine( 1, 
SetCireclet it, 
SetColor( EGA 
CLine( QO, 
tiLine<s. Gy 7 
CLine( O, 1 
CLinet G, 4 
Setcirclec QO, 
SetColor( EGA 
CLinet 0, @Q, 
CLineC 2; 
CiLIne< GC, 
CLine( @, 
SetCircle( O, 
SetCotort EGAL 
CLinet Oy Oy 


EGARed ); 
O52 
Oo, Dy 
Pee 
Oe 


7 
7 


7 
7 
7 


ah at ua C @) 


0, 
0, 
0, 


Ye, 


); 


L2é, Wt integer ); 


dyCY1i¢*dzylZ1], 
dyCY2jJ+dzylZ2J] ); 
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CELENGS Te ORS: Re ee eae 2s 
SetCirctet 0, Q, 0, EGABLack )3: 
CREAN Ue ts TY ae Pye te Ee 
Setcrretet 0, 17°, 8Gatyven »: 
Cie 8 Oy bie ae aren ae 
setCirete( 1, 1, 0, E£6AMNaGenta::): 


CLV nee ee Oy Tg Pe Eee eee. 
setCirevet t, 0, Ty: EBGABrGWN 23 
SetCirclet¢ t, ty, 1, EGALTohtGray 
SetColor(€ EGALightRed ); 


h 
CEU RSC ep Use De es ee Up ok. 2 
CUIWNOS 2). O06 Oy 25 Be ee OU OY 
setCirectet €, 0, 0, EGALTah tRed =) 
SetColor(€ EGALightBlue ); 

CLINE Se 25: Uy Ue ee 2a tT 2s 
CLINGS Oy Sy 10, 23 2507-42 
SetCiretet 0, 2, OQ, EGALIghtBlue 
SetColor€ EGALightGreen ); 

CLIMGA oe ie ga ee ae 
Chimes OO 25:0 2 eae els 


d; 


~ 
A 


iP: 


4 
setCiretlet 0, 0, 2, EGALightGreen ); 


Chiftiet 2. 25:0, 
SetCiroiet 2,. 2 
CERO oy ey ky Seo Re oe PE 

SetCircle( 0, 2, 2, EGALightCyan 


Ce ep eee ae 


CLIWOS 2 Uy £5 24 2s eee ae 
SetCireiet 2, 0, 2,° BGAYel lou >> 
SetCirecle( 2, 2, @, EGAWhite:); 


end; 


procedure ColorSwitch; 
var 
Done : boolean; 
Chis Hees 
begin 
Done := False; 
while not Done do 
begin 
Ch := Upcase( ReadKey ); 
if Ch = "Q*’ then Done := True 
1f Cotors then 
begin 
SetPalette( OQ, EGABLlack ); 
SetPalette( 15, EGAWhite ); 
Colors := False; 
end else 


7 
, O, EGALightMagenta ); 


ae 


else 
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begin 
SetPalette( 0, EGAWhite ); 
SetPalette( 15, EGABLlack ); 
Golors += True; 
end; ’ 
end; 
end; 


begin 
Initialize; 
Colors := False; 
Radius := 20; 
VAdj := GetMaxY div 60; 
for i := 0 to 2 do 


begin 
dylil s:= yFaclild * VAdj; 
dzyCil] := zyFaclild * VAdj; 
end; 


OutTextxY¢ 10, 10, 
"Enter <Q@> to quit or any key to change colors' ); 
ColorCube; 
ColorsSwite¢n; 
PrintPause( GraphDriver, FALSE ); 


CloseGraph; { restore text mode } 
end. 
{saeaSeeesseSeassseaseseessssesesc===z} 
{ Colors.PAS } 
{ Color Chart For EGA Mode/Palettes } 
{saaesaSeeeeeeseetssssessseesseescs=a===} 


uses GRAPH, CRT; 


var 
GraphDriver, GraphMode, 
MaxColors, ErrorCode, radius : integer; 
palette : Palettetype; 
StepForward : boolean; 


procedure Initialize; 
begin 
GraphDriver := DETECT; 
InitGraph( GraphDriver, GraphMode, '\TP\BGI' ); 
ErrorCode := GraphResult; 
if ErrorCode <> grOk then 
begin 
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writeln(€' Graphics System Error: ', 
GraphErrorMsg( ErrorCode ) ); 
nhettc 1.2 
end; 
end; 





procedure PrnNum( x, y : integer; Buffer : string ); 


begin 
SetViewPort( x-20, y~=4, x+20, y+9, True ); 
ClearViewPort; 


SetViewPort( 0, 0, GetMaxX, GetMaxY, True ); 


Outtextanrt k> ¥, Butver 2s 
end; 


procedure LabelColors( i : integer ); 
var 
Butfer * string: 
begin 
strt -patvette.colorelid:2) butter..>3 
if i > 7 then PrnNum( 80*i-600, 138+radius, 
else PrnNum( 80*i1+40, 58+radius, 
end; 


procedure ShowColors; 

var 
1 2+ Integer: 

begin 
GetPalette( palette ); 
for 342 OS 7 do 
begin 
SetFillStyle€ SolidFill, 1 0; 
Circte( 80*1+40, 50, radius ); 
FLOOGFILL( 80*14+40, 50, GetColor ); 
LenetColors<( 1): 
SetFitl$Stylet SolidFill, 1+8 ); 
Circle 80*1+40, 130, radius ); 
FlLOoodFILL( 80%*1+40, 130, GetColor ); 
LabelColors( it8 ); 

end; 

end; 


procedure ColorwWheel; 
var 

1 2 tnteger: 
begin 

FOP 2 Pei 26 4S do 


buffer.) 
buffer 
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begin 
SetFittstytet SotteFttit, T3+4-);7 
PieSticet€ 320, 270, trune( 42¢2.5 2, 
trune( €4491)*22.5 .), radius*3 ); 
end; 
end; 


procedure StepColors; 
var 
i, ThisColor : integer; 
Ch © ener; 
Done : boolean; 
begin 
Done := False; 
while not Done do 


begin 
Ch := upcase( ReadKey ); 
Done := Ch = ‘Q'; 
if Ch = '-' then StepForward := False; 
if ch = '+' then StepForward := True; 
if not Done then 
begin 
for + += .0 to 13-89 
begin 
ThisColor := patlette.colorslid; 
if StepForward then inc( ThisColor ) 
else dec(€ ThisColor ); 
if ThisColor < 0 then ThisColor := 63; 
if ThisColor > 63 then ThisColor := 0; 
SetPalette( i, ThisColor ); 
GetPalette( palette ); 
LabelCotors€ 7 23 
delay(30); 
end; 
end; 
end; 


end; 


procedure InitializeColors; 
var 
1 : tateger; 
begin 
for i := 0 to 15 do SetPalette( i, i ); 
end; 


begin 
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Initialize; 
radius := 30; 
StepForward := True; 
SetTextJustify( CenterText, CenterText ); 
SetTextStyle(€ SansSerifFont, HorizDir, 1 ); 
OCutTextcys 320, 0,5 
"Enter <Q@> to quit or any key to change colors' pe 

OutTextxy< 100, 250, ‘Enter <-> for! >); 
OutTtextxy¥( 100, 270, ‘reversed step’ ); 
OutTextxyY< 540, 250, "Enter <#> for' *): 
OutTextxyY¢ 540, 270, ‘forward step' ); 
InitializeColors; 
ShowColors; 
ColorWheel; 
StepColors; 
CloseGraph; 

end. 


Part 3 


Object-Oriented Programming In 
Turbo Pascal 


The object in object-oriented programming is simply a generic label for a program- 
ming element, but the object in question is define by what it is not. This is because 
the object is not individually a procedure or a function, nor is the object a variable 
or a data type. 

Instead, the object in question is composed of all of these elements and the 
relationship between these elements. This encompasses a new degree of modularity 
in which data, variables, procedures and their relationships comprise a new mod- 
ular element called an object. 

Centuries ago, chemistry (then called alchemy) dealt with a series of relation- 
ships and qualities that were sometimes called influences, sometimes primal sub- 
stances (air, earth, water and fire were four of these). Later, chemists began to 
identify, first, chemical compounds, then chemical elements and, a few decades ago, 
sub-atomic elements and elementary particles. 

With computers, however, we have been working in the opposite direction. We 
began with our primal particles, simple binary switches, proceeded by building 
atoms in the form of computer instructions, began combining these atoms into 
chemical-equivalents called programs (we are presently at the level of creating 
aspirin ... and needing it!) and are moving toward the discovery of tailored con- 
structs of the complexity level of plastics. If you remember punchcards—as | 
do—don’t let the white beard get in your way, experience still counts for something. 
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Object-oriented programming is the next big advance, allowing us to tailor our 
atoms in order to create custom materials of greater complexity than previously 
possible and to do so with greater ease and convenience than previous languages. 

Incidentally, if you have been a programmer or even a computer hobbyist for 
five years or more, take a moment to remember what programming was like when 
you first entered the field, remember those early days? 

Welcome to the next step forward! 


Topics and Treatment 


Object-oriented programming is a tool that can be applied to virtually any task and 
the first object-oriented language, Simula-67, was a tool designed to model the 
operation of mechanisms—or objects. Object-oriented programming is not so 
restricted in its uses and the applications shown here will be more general and 
diverse. 

The first examples used to demonstrate principles of object-oriented program- 
ming will be simple graphics applications because graphics provide a natural 
environment for teaching object-oriented programming, allowing you to, quite 
literally, see what the objects are doing. 

Because many programs—with the recent advances in both computers and 
languages—are becoming graphic-oriented, object-oriented graphics will be one of 
the topics covered in greater length. 

The new OS/2-Presentation Manager system is almost totally graphics-ori- 
ented even for routine text displays and, incidentally, is also object-oriented (though 
more restrictively so than Turbo Pascal 6.0). 

Graphics imply the use of a mouse as an input device, therefore, one of the first 
object applications will be an object-oriented mouse that will later be used with 
control objects in the form of graphics buttons. 

Object-oriented programming is far from limited to graphics and more conven- 
tional programming operations will also be covered, including using the mouse 
and button controls in text as well as graphics applications. 

But this is enough preface—let’s move on to theory and practice and see how 
object-oriented programming works and how it can be used to improve and 
enhance your programming practices. 


Chapter 28 


Object-Oriented Practices 


In this chapter, several example programs will be used to demonstrate the basic 
elements of object-oriented programming without attempting to accomplish any 
overly complex tasks. At the same time, the precepts governing object-oriented 
programming will be explained and illustrated; together with their possible prob- 
lems and pitfalls. 

First, here is an overview of the three principal properties that dominate 
object-oriented programming: inheritance, encapsulation and polymorphism. 


» Inheritance is a property of objects. It allows for the creation of a hierar- 
chy of objects with descendants of objects inheriting access to their 
ancestors’ code and data structures. 

» Encapsulation is modularity applied to data. It combines records with pro- 
cedures and functions—called methods—that manipulate data, forming a 
new data type called an object. 

s Polymorphism is the property of sharing a single action (and action name) 
throughout an object hierarchy. Each object in the hierarchy implements 
the action in a manner appropriate to its specific requirements. 


Inheritance 


Much of science is concerned with hierarchies and relationships (or artificial 
relationships), between objects. Fossil archaeology looks for relationships between 
extinct species and historians record sequences of events and dynasties and seek 
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to understand relationships between causes and events. Biologists classify insects, 
plants and animals by taxonomy; genealogists draw and study family trees and 
stock market analysts study price fluctuations. All of these are studies of relation- 
ships between individual events, studies that may, in some way, provide predictive 
information. 

All of these “charts,” however, are based on the concept that objects lower in 
the hierarchy are influenced by, inherit characteristics from, or are descended from 
those above them in the chart. 

Figure 28-1 shows a classification hierarchy for objects of type vehicle. On the 
top level, we find the object “vehicles” and, in the first generation of descendants, 
the vehicles object is broken down into four very different operating mediums: 
water, land, air and space, which seem to have little in common. 


Figure 28-1: Vehicular Family Tree 
et — RSA Paso Ns La kN See RM Na Se OR CR a tI ee 
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Objects in each of these second generation categories have inherited one 
principal characteristic from their parent object; each has the characteristic defined 
as “vehicle” and; therefore, has inherited some property that separates a vehicle 
from, for example, a plant, mineral or animal. 

In the third generation, objects of the class “surface” and “submarine” appear 
below “aquatic,” but both have inherited the characteristics “vehicle” and 
“aquatic” from their parent generation. This classification tree can be carried 
further, but in each case, any specific object inherits all of the characteristics that 
defined its parent object, and its parent's parent. 


Object Inheritance by Declaration 


As an example of how object inheritance operates, four variable types have been 
declared (in Table 28-1), on the left as record types and, on the right, as object types. 
A taxonomy chart appears in Figure 28-2. 


Table 28-1: Record Declarations vs. Object Declarations 


Record Declaration Object Declaration 
Loc = record Loc = object 
Xx, Y : integer, xXx, y : integer; 
end; end; 
Point = record Point = object( Loc > 
Where : Loc; Color : integer; 
Color : integer; end; 
end; 
Rect = record Rect = object( Point ) 
Pixel : Potnt; SX, SY HK -integer; 
SX; s¥Y %. tHteger? end; 
end; 
Circl = record Cipel w@ obfect*< Potnt 2 
Pixel : Point; rx : integer; 
rx : tnteger; end; 
end; 
ELlip = record ELLip-=#object( Ciret 2) 
Pixel 2 Point; ry : integer; 
rmx, ry : integer; end; 


end; 
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In Figure 28-2, the four object variables appear in a tree relationship. As you 
can see, these four variable types can be declared either as records or as objects. The 
advantage of declaring them as objects is not because the source code is slightly 
shorter (the .EXE code will be slightly longer); instead, look at the two source code 
listings for OOPTest1 and OOPTest2: 


Figure 28-2: An Object Hierarchy with Inheritance 





OOPTesti—Using Records 


In the first example, the variables are declared as record types similar to the 
examples in the left column in Table 28-1, and in the second case, as object types 
similar to the examples in the right column of Table 28-1. 


program OOPTest1; 


uses: Crt; 


type 
Location = record x, y : integer: end; 
Point = record Pixel ; ROCHE On: 
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Color . §nteger:; end; 
Circle = record Place : Points 
radius : integer, end; 


var 
TestPt : Lecation; 
ACirctle ¢«¢ Cire le; 


begin 
TestPt.x 22 10; 
TestPt.y 2= 20; 


Assigning values to the TestPt variable is simple (and it should also be a familiar 
practice). The values for the variable ACircle are not so easily referenced. 
{ aACircle.x <= 30; + { Field identifier expected } 
{ ACircle.Pixel.x := 30; } { " . ? t 
Either of the two preceding attempts to reference the field element x would 
produce the error message shown. 
For the record type variable, the entire genealogy of the record structure has to 
be explicitly referenced to both assigned values: 


ACircle.Place.Pixel.x := 30; 
ACircle.Place.Pixel.y := 40; 
ACircle.Place.Color = 50; 
ACircle.radius = 60; 


And to subsequently access the assigned values: 


CLYegers 
writeln( ACircle.Place.Pixel.x ); 
writeln( ACircle.Place.Pixel.y ); 
writeln( ACircle.Place.Color ); 
writeln( ACircle.radius ); 
writeln( TestPt.x ); 
writeln( TestPt.y ); 
writeln; write('Press ENTER to proceed'); 
readln; 

end. 


OOPTest2—Using Objects 


In the second example, the same record structures and variables are created, but 
this time, the variables are of type object. 
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program OOPTest2; 


uses Crt; 


type 
Location = object x, y : integer; end; 
Point = object( Location ) 
Color: integer; end; 
Circle = object( Point ) 


radius : integer; end; 


The parenthetical expressions following object—(Location) in one case and 
(Point) in the other—name the immediate ancestors of the objects being declared. 
Notice also that the object Location has no ancestor while, unlike humans, objects 
have one immediate ancestor at most. 

At this point, the data type Circle has inherited the same equivalent data fields 
as if it had been declared as: 


Circle = record 

X, Y, Color, radius : integer; 

end; 
Note the qualifier, equivalent, in this simple example. Equivalence is easy, but 

as the object types become less simple, the equivalence will be less apparent and 

less real. For the moment, however, let’s continue with the example: 


var 
TestPt cc hocaetions 
ACircle : Circle; 

begin 
TestPt.x = 10; 
TestPt.y = 20; 
ACircle.x = 30; 
ACircle.y = 40; 
ACircle.Color = 50; 
ACircle.radius := 60; 


Even though the structure elements in ACircle were not explicitly declared in 
the type declarations and even though their genealogy is not referenced in the value 
assignments, the elements x, y and Color accept values without difficulty. In actual 
fact, | do not have to know the genealogy of the data type Circle at all—just as long 
as I know what elements exist in the object Circle. These same record elements are 
read back with no more difficulty than they were originally assigned. 
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ct rser? 

writeln(ACircle.x); 

writeln(ACircle.y); 

writeln(ACircle.Color); 

writeln(ACircle.radius); 

writeln(TestPt.x); 

writeln(TestPt.y); 

writeln; write('Press ENTER to proceed'); readln; 
end. 


Please note, while it is possible to assign values to an object's fields—as shown 
in the preceding example—this is very bad practice and should not be followed. The 
reasons for this caution and the practices that should be used will be demonstrated 
momentarily (see the Methods section). This shortcut was employed here to pro- 
vide an uncomplicated example of the nature of inheritance fields. 

As with conventional Pascal records, the data fields could also have been 
assigned using the with...do statements: 


with ACircle do 


begin 
x =. - $3 
y = 40; 
Color = 50; 
radius := 60; 
end; 


Again, the same caution applies: while this form will work, it is not good 
practice and should not be employed as normal procedure. 


Object Inheritance Terminology 


In the example OOPTest2, the record type Loc was declared as an object type and 
the variables TestPt and ACircle became object variables. 

The data type, Location is the ancestor of the data type Point, while the data type 
Circle is the descendant of Point, which is the descendant of Location. 

In similar fashion, in Figure 28-2, both Circl and Rect were descendants of Point. 
Note that sibling relationships are not relevant, only descendance and ancestry and 
the inheritance from ancestor to descendant. 


Methods 


To object-oriented programming, methods or object methods are the equivalent of 
procedures and functions in conventional programming and, in actual fact, they 


522 USING TURBO PASCAL 6.0 





are composed of procedures and functions that are similar, but work in a new way. 
As with all programming, they require recognition of their capacities and of their 
limitations. ; 

Previously, the data fields of the objects TestPt and ACircle were initialized with 
direct assignment references: 


TestPt.x = 10; 
and: 
ACircle.x = 30; 


A second instance was shown using a with..do assignment. A caution was 
appended, however, stating that neither was the best form for assigning values to 
objects. 

Granted, both assignments worked, but each descendant of the object type 
Location required separate and specific instructions to assign values to each data 
field—a process that is tedious and repetitive at best and, in real programming 
practices, can quickly become an annoyance. 

The obvious alternative would be to create a procedure containing generalized 
assignment statements and to pass objects of type Location (or objects that have 
inherited Location’s data structure) as variable parameters: 


procedure SetLoc( var Coordinate : Location; 
PEA Pty. 2 integer 2: 
begin 
Coordinate.x = PtX; 
Coordinate.y = PtyY; 
end; 


Now, assignments can be carried out in the form: 
Setloct -feetrt, 10, 20°23 
and: 
SetLoct AGtircte, 30,: 4033 


This will work for all objects of type Location and for all descendants of objects 
of type Location, but it is still not the best way to assign values. As the objects 
become more complex, in many cases, this approach will not work at all or will 
work very awkwardly. This is neither the intent nor the objective of object-oriented 
programming. 
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Instead, to manipulate data belonging to objects, methods are created. A 
method is a procedure or a function that becomes integral to a specific object type 
(and, of course, it is subject to the same rule of inheritance for descendants). In this 
fashion, the data structure—the object—and the procedures serving the data—the 
methods—are fused together into a single unit so that access to each is available by 
default, and does not require explicit provisions for access or assignment in every 
case. 

How does a method work? In its simplest form, consider the following code: 
type 

Location = 
object 
Xx, ¥-t PHteger? 
procedure SetLoc( PtX, PtY : integer ); 


function GetX : integer; 
function GetY : integer; 
end; 


What's happening here—a procedure and two functions being declared as if they 
were fields in a record structure? 

That’s exactly what’s happening. The procedure SetLoc and the functions GetX 
and GetY have become part of the object type Location and are now a portion of 
the record. 


OOPTest3—Using Methods 
The procedure SetLoc and the functions GetX and GetY still have to be defined: 


procedure Location.SetLoc( PtX, PtY : integer ); 


begin 
x 3:= PtX; 
y £2 PY: 
end; 
function Location.GetX : integer; 
begin 
GetX = x; 
end; 
function Location.GetY : integer; 
begin 
GetY = y; 


end; 
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For each of these, the object Location is referenced because, in other cases, there 
may be two or three or several SetLoc procedures along with any number of Get... 
functions, each referencing different object types and executing different tasks. 

Finally, to use the SetLoc procedure. It is called as though it were merely a field 
of a record: 


var 
FOS TRE 2: Locations 


TesextPrr SetlLoct T0520 2; 


What could be simpler? The SetLoc procedure, which is a method belonging to 
the object type Location, is called with two parameters which are then automatically 
assigned to the appropriate fields. Remember that the method SetLoc will also be 
inherited by all descendants of the object type Location. In like fashion, the 
functions GetX and GetY are called as TestPt.GetX or TestPt.GetY to return the 
specific values from TestPt. 


Finally, the example OOPTest2 is revised, becoming OOPTest3, and using 
methods to assign and return values: 


program OOPTest3; 
uses Crt; 
type 
Location = 
object 
Ko ¥ous integer: 
procedure SetLoc( PtX, PtY : integer )-> 
function GetX : integer; 
function GetY : integer; 
end; 


Point = 
object( Location ) 
Color: integer; 
procedure SetColor(€ c: integer ); 
function GetColor : integer; 
end; 


Ci reta-*s 
epiect<« Point ?) 
radius : integer; 
procedure SetRadius( r : integer ); 
function GetRadius : integer; 
end; 
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var 
TestPt ss Locatien? 
ACirocle ¢ Ciretsé; 


Notice that seven different methods have been referenced as subsequent gen- 
erations were declared. Because each of these methods is a separate procedure or 
function, each must be defined. Granted, the definitions are simple in this example, 
but this will not always be the case in the future: 


procedure Location.SetLoc( PtX, PtY : integer ); 


begin 
Xx = PtX; 
y = Pty? 
end; 


function Location.GetX : integer; 
begin 

GetX = x; 
end; 


function Location.GetY : integer; 
begin 

GetY = y; 
end; 


procedure Point.SetColor( c : integer ); 
begin 

Colter = ¢y 
end; 


function Point.GetColor : integer, 
begin 

GetColor = Color; 
end; 


procedure Circle.SetRadius( r : integer ); 
begin 
radius := r; 
end; 
function Circle.GetRadius : integer; 
begin 
GetRadius = radius; 
end; 


Now that the procedures used for the methods are defined, the original six 
direct assignments used in OOPTest2 are replaced with four method calls: 
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begin 
TORTPE Setioct 10, 20 >; 
ACiretve Settioct 30,40 ); 
ACitrete.SetCotort 50: >)» 
ACircle.SetRadius( 60 ); 


Admittedly, the overall savings of two lines of code in the main procedure is 
certainly not enough to warrant the extra effort required to declare the method 
procedures, but the example here is a simple one. In more complex cases the savings 
will make a difference. To complete the example, the final portion of code uses the 
objects’ functions to return the values: 


Ctrsers 

writelnCACircle.Getx); 

writelnCACircle.GetyY); 

writelnCACircle.GetColor); 

writelnCACircle.GetRadius); 

writeln€TestPt.GetxX); 

writeln(€TestPt.GetY); 

writeln; 

write('Press ENTER to proceed'); readln; 
end. 


Encapsulation 


Encapsulation is a term for the process of combining both code and data into an 
object, a process that was demonstrated in the examples in OOPTest3. 

In some object-oriented languages, such as Smalltalk, encapsulation is strictly 
enforced and data elements belonging to an object are only accessible through the 
methods provided with the object. If no method is provided to read or write an 
object’s data element (from outside the object), then the data cannot be directly 
accessed by the programmer. 

In Turbo Pascal, however, encapsulation is provided and supported but is not 
enforced. As shown in OOPTest2, any object data element can be accessed directly 
either to read the data values or to change the data values. 

The flexibility of object-oriented Pascal, providing encapsulation without 
enforcing encapsulation, offers the programmer broader opportunities and, at the 
same time, demands greater responsibility in exercising correct object-oriented 
programming practices. 

In object-oriented programming (in theory) it should be unnecessary to ever 
access an object’s internal data fields directly. The programmer should always 
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provide methods to access objects’ internal data fields, but what “should be” is not 
enforced and direct access is not prevented. 

One of the capabilities of object-oriented programming is the ability to create 
libraries that extend Pascal’s inherent capabilities, and these libraries can be dis- 
tributed for use by other programmers. As a result, itis doubly important for proper 
access methods to be provided, for these methods to be documented and, since 
encapsulation is not enforced, for the data fields belonging to objects (and their 
identifiers) to also be documented. 

The question of distributing object libraries is a topic of its own and will be 
covered later in detail. For the moment, however, please keep in mind that any 
object-oriented library can be distributed and that Turbo Pascal’s open encapsula- 
tion standards impose greater demands than a more rigorously enforced encapsu- 
lation. Even if you develop objects only for your own use and never distribute the 
“raw” object libraries, the demands of proper encapsulation and proper methods 
should still be observed, simply for your own convenience. A few examples of the 
possible pitfalls in object-oriented programming will be shown in later examples. 


Program Organization 


A variant program organization is being used for the demo programs in this book; 
primarily for purposes of explanation and not because object-oriented program- 
ming requires any special variation in style. A general program structure appears 
in Figure 28-3. 

Notice that the type declaration for each object is followed immediately by the 
method definitions that are created for the object. Only after all of the objects have 
been defined are the global variables, the non-object procedures and functions 
listed. 

There is no firm rule requiring this organization; the program’s global variables 
could appear at the beginning of the program listing, then the object declarations 
grouped together with the method definitions following or the global variables 
could follow the type declarations. The overall structure is generally unimportant 
and the organization shown is intended simply to group elements for your conve- 
nience in reference. 

There is, however, a secondary reason. When defining methods for objects, the 
programmer should be particularly careful to ensure that all variables used are local 
to the method (i.e., local to the procedure or function), with the exception of those 
variables that belong specifically to the object. 
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Figure 28-3: Demo Program Organization 


Program header, 
uses units, etc 


var 
global variables, etc 


other procedures, functions 
main procedure 





For several reasons, global variables should never be referenced by an object's 
methods. First, it’s difficult to ensure that a global variable is not being used for 
some purpose that may be incompatible with the object’s use. Second, using a 
global variable directly or indirectly circumvents the concept of encapsulation. 
Third, any object using a global variable is not cleanly transportable (as with the 
Mouse and Button objects that will be created in Chapter 29, but transported for 
use in subsequent programs). 

One method of ensuring that global variables are not accidentally utilized by 
methods is to have a program’s global variable declarations follow the object and 
method definitions, as shown in the general program organization. If for any reason 
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this organization or any of these guidelines prove impractical, exceptions will 
occur. 


OOPTest4—Using Polymorphism 


The term polymorphism is taken from Greek, meaning “many shaped.” Itis amethod 
of giving an action a single name that is shared throughout an object hierarchy, but 
accomplishes the named action in different fashions (as appropriate to the specific 
object referenced by the action). For example, in OOPTest4, three object types will 
be declared in order of descent; Point, Circle and Square—the object names should 
be essentially self-explanatory. 

The object Point is the simplest screen image possible, a single pixel, and it is a 
duplication of a point in the video memory. Point is also an object and, in some 
respects, is more accessible than the video memory. It also has several methods that 
are not directly provided for video access. The object Point begins with three record 
values: 


type 
Point = object 
x, VV, Coteor © integer; 


and provides seven methods for access: 


procedure Create( PtX, PtY, 
C : integer ); 
procedure Destroy, 
procedure Move( PtX, PtY : integer ); 
procedure SetColor( C : integer ); 
function GetX : integer; 
function GetY : integer; 
function GetColor : integer; 
end; 


In brief, the method Create creates a point with the specified location and color, 
Destroy removes the point, Move changes the location and SetColor changes the 
color of the point. Finally, the last three methods return information about the 
referenced point. (The complete code for the object Point appears in the program 
listing at the end of this chapter.) The second object, Circle, is a descendant of Point 
and adds one new record, size. It also redeclares several of the methods that were 
inherited from Point—Create, SetColor and Destroy—as well as declaring a new 
method, GetSize. 
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Circle = object( Point ) 
size : integer; 
procedure Create( Ptx, PtY, 
R> £23 3nteger.) 
procedure SetColor( C : integer );> 
procedure Destroy; 


function GetSize : integer; 
end; 

The redeclaration of the Create, SetColor and Destroy methods are examples 
of polymorphism—the name of the method and its general function are inherited, 
but the specific implementation for each of these methods has been redefined in 
order to perform appropriately for the new object. The method GetSize is new 
because the object Point does not have a size. 

Note: if you refer to the program listing at the end of this chapter, you will notice 
that several other methods, including Move and SetColor, are redefined for both 
Circle and Square. Three methods, however, are sufficient for illustration here. 

The third object type, Square, is a descendant of Circle and does not declare any 
new variable records, but it does redeclare the methods Create, SetColor and 
Destroy; redefining each as appropriate for Square: 


Square = object( Circle ) 
procedure Create( PtX, PtY, 
Ry 65s 3nteger 2; 
procedure SetColor( C : integer ); 
procedure Destroy; 


end: 
The method GetSize is neither redeclared nor redefined because the same 
GetSize method works for both Circle and Square. The methods GetX, GetY and 
GetColor, which are inherited from Point, are not redefined at all. 


Polymorphing the Create Method 


When the method Create is originally defined for the object point, only three 
arguments are required: the x and y coordinates and the color: 


procedure Point.Create( PtX, PtY, C : integer dy 


begin 
Ee TMM oaks Sa 
¥- 43 PEYs 
COLGM sa 50 5 
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PutPixel( x, y, Color I; 
end; 


Create ends by calling Turbo’s PutPixel function with the values to set the 
screen pixel. 

With Point’s descendant, Circle, a fourth parameter, the radius, is required. The 
subsequent actions are also different because the Graph functions SetColor and 
Circle are called to execute the actual screen write: 


procedure Circle.Create( PtX, PtY, R, C : integer ); 
begin 
x PtX; 
y al Bb i 
color :2- ; 
size := R; 
Graph.SetColor(€ color ); 
Graph.Circle( x, y, size ); 
end; 


Also notice that the Graph functions are explicitly referenced (Graph.SetColor 
and Graph.Circle) to distinguish these from the object Circle and Circle’s method, 
SetColor. 

For the object Square, Create is redeclared. The arguments are the same as for 
Circle, but the execution is different. 


procedure Square.Create( PtX, PtY, R, C : integer ); 


begin 
XK s= PUA 
y i= PtTZ 
CoLOe?. +e E2 


size := R; 
Graph.SetColor( color ); 
Graph.Rectangle( x-(size div 2), y+t(size G40 225 
x+{size div 2), y=Csize adiv.é2..2; 
end; 


Since Circle is determined by a center point and a radius (size), Square has been 
defined in terms of the same three parameters with size being used as the square 
analog of the radius so that the total height and width of each square is twice the 
“radius.” This is not necessarily the best way to program this object; simply the best 
for illustrating the subject. 
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The Polymorphic Destroy and SetColor Methods 


The Destroy method is also redefined appropriately for each of the three objects. In 
all three cases, Destroy calls the Create method and uses GetBkColor to provide the 
background color value to redraw the pixel, circle or square to match the back- 
ground: 


procedure Point.Destroy; 
begin 

Create( x, y, GetBkColor N 2 
end; 


procedure Circle.Destroy; 
begin 

Create( x, y, size, GetBkColor ); 
end; 


procedure Square.Destroy; 
begin 

Create( x, y, size, GetBkColor ); 
end; 


Why has the Destroy method been redefined for each object type? This is neither 
accidental nor unique—take a look at the three redefinitions for the SetColor 
method: 
procedure Point.SetColor( c : integer ); 
begin 


Create( x, y, Color eS 
end; 


procedure Circle.SetColor( C : integer ); 
begin 

Createt x, yy, s12¢,. €. 23 
end; 


procedure Square.SetColor( C : integer ); 
begin 

Ceeptet: £) Vo 6126, .C  )% 
end; 


Precisely the same thing is being done here—the coding is identical for Circle 
and Square, just as it was for the Destroy method(s). This has been illustrated for 
emphasis because it is a very important point! 

The Destroy method(s) could have been defined: 


procedure Point.Destroy; 
begin 
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Point.Create( x, y, GetBkColor 2 
end; 


procedure Circle.Destroy; 
begin 

Circle. Create: Xo. ¥, Size, GetBkColor 2; 
end; 


procedure Square.Destroy, 
begin 

Square.Create( x, y, size, GetBkColor ); 
end; 


to show the fact that each version of Destroy is calling the specific version of Create 
which is appropriate to Point, Circle and Square in each case. However, if the 
method Destroy had not been redefined for each generation of object, the results 
would have been very different. 


Subtle Error #1 


If the redefinition of Destroy was omitted from the object Square, an attempt to 
Destroy an object of type Square would actually erase a corresponding object of 
type Circle (the most recent ancestor type possessing the appropriate method). 

In this case, the x and y coordinates and the size value used would belong to 
the referenced Square object, but the Destroy method would be calling Circle.Cre- 
ate, not Square.Create. This can be a very obvious error in some cases or a very 
subtle error in others. In the current example (with the pointillistic background 
provided by the program), the error should be relatively obvious and [recommend 
attempting the experiment of commenting out both the procedure declaration 
within the object definition and the procedure definition itself in the OOPTest4 
program source code. In other cases, the error can be very difficult to find. 


Subtle Error #2 


In the OOPTest4 demo program, use Turbo Pascal’s editor facilities to globally 
change the variable MaxC to Color. Note: if you are manually entering the program 
listing, be sure that it runs correctly before attempting this experiment. You might 
also use the Watch facility and type in the variable Color for tracking. After making 
this change, run the program again. Within a few moments you should get the 
message: Fatal Error 200: division by zero. 

Turbo Pascal will indicate the error has occurred in the following block of code 
but, if you are using the Watch facility to track the value of Color, the value shown 
is not zero, so what’s going on? 
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repeat 
TOT Ree 7 to. 32 do 
with ACireleltd do 
SpetColtor( € GetCotor =. 1) mod Cotor ); 
until KeyPressed; 


It’s another very subtle error. The Color variable in the Watch facility is not the 
same Color variable that is causing a very real divide by zero error. The Color 
variable above is not the global variable Color which has the value returned by 
GetMaxColor, but is ACircle[i].Color which can reach a value of zero. This is one 
of the possible errors that can be caused by the lack of strictly enforced encapsula- 
tion (and also why I suggested typing in the variable name). 

If you are aware of the possible pitfalls—and tread carefully—most of the errors 
are easily avoided. 


Summary 


In this chapter, a few aspects of object-programming have been demonstrated. In 
Chapter 29, object-oriented programming will be used to create an object-oriented 
mouse for both text and graphics applications. 


(SSSSSSSSeSSeeseeeeeeeeeee=====} 
{ OOPTest4 Program Listing } 
(SSSSSSSSesSeeeneseeesseezsezecz} 
uses Crt, Graph; 
type 
Point = object 
Keo Vp COAG fF teaser: 


procedure Create( PtX, PtY, 
Cot jnteger: -):} 

procedure Destroy; 
procedure Move( PtX, PtY : integer ); 
procedure SetColor( C : integer ); 
function GetColor : integer; 
function GetX : integer; 
function GetY : integer; 

end; 


procedure Point.Create( PtX, PtY, C : integer ae 
begin 

xX Leek 

yY $3::7273 

Color) 3 ¢3 

PUTPIXOCC x,y, Cotor )+ 
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end; 
procedure Point.Destroy; 
begin 
Create( x, y, GetBkColor ); 
end; 
procedure Point.Move( PtX, PtY : integer 
begin 
Destroy; 
x £= PX? 
y ¢= Pt? 
Createt x, vo CBLlLor.?; 
end; 


procedure Point.SetColor( c : integer }' 5 
begin 

Createt Xs ¥- © 2g 
end; 


function Point.GetColor; 
begin 

GetColor := Color; 
end; 


function Point.GetX; 
begin 

GetX := x; 
end; 


function Point.GetY; 
begin 
GetY := y; 
end; 
type 
cCirpele = object( Potnt 2 
size : integer; 


procedure Create( PtX, PtY, 
integer ); 
procedure SetColor( C : integer ); 


R, C 


procedure Destroy, 
procedure Move( PtX, PtY 


integer ); 


procedure SetSize( R : integer ); 
function GetSize : integer; 


end; 
procedure Circle.Create( PtX, PtY, R, C 
begin 
x = PtX; 
y 2 PUY? 


integer ); 
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size RS 

cooler t Cs 
Graph.SetColor( color ); 
Grapnetirctet x, ¥, size 


end; 


procedure Circle.Destroy; 
begin 


Createt x, vy, size, 
end; 
procedure Circle.SetColor( C 
begin 

Create( x, y, size, C ); 
end; 


procedure Circle.Move( PtxX, 
begin 
Destroy; 
Create( PtxX, 
end; 


POY». £4128; 


procedure Circle.SetSize( R 
begin 
Destroy; 


Creetvet: x, ¥, oR, color): 
end; 
function Circle.GetSize; 
begin 

GetSize := size; 
end; 
type 

Square = object( Circle ) 


procedure Create( PtxX, 


Set 
Des 


procedure 

procedure 

procedure 

procedure 
end; 


procedure Square.Create( PtxX 
begin 
x 


Wicks 


PtX >s 

rPtYs 

stze-.x Ks 

Color C2 
Graph.SetColor( color ); 


Graph.Rectangle( x-(size div 2), 


MoveC PtX, 
SetSize(€ R 


Ee 


GetBkColor ); 


integer ); 


PE EAE 22 


CoLor: 2} 


integer ); 
ich 
Rees IT Reeger ss 
Colort:-C. 4 Intecer ys 
troy; 


Pty 3 Anteger 
integer ); 


a3 


po PETS URS. EF integer ); 


y*(size div 2), 
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x+#(size div 2), y-(size div 2) ); 
end; 


procedure Square.Destroy; 
begin 

Create( x, y, size, GetBkColor ); 
end; 


procedure Square.SetColor( C : integer ); 
begin 

Create x, ¥, size, © 2; 
end; 


procedure Square.Move( PtX, PtY : integer ); 
begin 

Destroy; 

Create( PtX, PtY, side, Color ); 
end; 


procedure Square.SetSizeC R : integer ); 
begin 

Destroy; 

Ctreeate( x, Me Rp eOber: 77 


{=========== end of object methods ============} 


TestPt : Point? 

ACircle.: arrayl1..323 of Circle; 

ASquare : arrayl1..321] of Square, 

i, MaxX, MaxY, MaxC, GDriver, GMode, GError, 
Cx, Cy, Size, TestColor : integer; 

ch Y ere? 


begin 
GDriver := Detect; 
InitGraph( GDriver, GMode, '\TP\BGI' 2.2 
GError := GraphResult; 
if GError <> grOk then 
begin 
writeln('Graphics error: ',GraphErrorMsg (GError)); 
writeln('program aborted...'); 
REL CRTs 
end; 
{ create a background } 
ClearDevice; 
MaxC := GetMaxColor; 


for 1 := 1 to 10000°a0 
TestPt.Create( random( GetMaxX ) + 1, 
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random(€ GetMaxY ) + 1, 
random( MaxC ) + 1 ); 


{ draw receding circles } 


Cx GetMaxX div 2; 
Cy GetMaxY div 2; 
Size := GetMaxY div 2; 


Tot feo 7 £56 ° 32 do 
begin 
ACircleljid.create( Cx, Cy, Size; 1 23 
dec€ Size, 8 )s 
Gect Cx ,.°40 d2 
eee Cy,- 4 3 
end; 


repeat 
Tor Ao see 2 te BA do 
with ACircleLCild do 
SetColor(€ (€ GetColor - 1 ) mod Maxc ); 
until KeyPressed; 
Ch == ReadKey; 


for i := 1 to 32 do ACirclelil.Destroy; 
{ draw receding squares } 


Cx 2 * GetMaxX div 3; 
Cy GetMaxY div 2; 
Size := GetMaxY div 2; 


TOP: 3 2 oy ty - 32 ae 
begin 
Asquarelis.Create( Cx, Cy, Stee, 4 >}; 
dect $tz8, 6 )-» 
GOs  4%,10.') 3 
GOs: -f¥ 04 ps ~ 3 
end; 


repeat 
TOR) te 4. ta 3e dé 
with ASquareLild do 
SetColor(¢ (¢ GetColor - 1 ) mod Maxc a 
until KeyPressed; 
Ch := ReadKey; 


for i := 1 to 32 do ASquarelil.Destroy; 


repeat until KeyPressed; 
end. 


Chapter 29 


An Object-Oriented Mouse 


Most graphics programs use the mouse as a primary interface device. This book 
will, therefore, begin the graphics programming applications with an object-ori- 
ented mouse unit (MOUSE.PAS and MOUSE.TPU) and with a_ utility 
(MOUSEPTR.PAS) to create mouse cursor images that can be incorporated in the 
mouse unit or directly into your applications. 

The programs in this chapter (and many of the later chapters) assume that your 
computer has a bus or serial mouse and mouse driver (Microsoft, Logitech or 
compatible) installed. The mouse unit created in this chapter is not itself a mouse 
driver, but an interface that uses the driver utility supplied with your mouse 
hardware. 

When creating an object unit for use either by yourself or for distribution and 
use by other parties, it is helpful to provide descriptive documentation listing what 
functions are available via the unit, the parameters required to call these functions, 
and any data structures that are used by the object unit and are available to the 
calling program. For the MOUSE.TPU unit, sample documentation appears in 
Appendix B. 


The Case of the Bashful Mouse 


If you are using VGA or higher resolution graphics, and the mouse pointer does 
not appear in the graphics application, the problem may be in your mouse driver 
and can be cured by installing a newer driver package. The problem can be tested, 
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however, by using Turbo Pascal’s SetGraphMode command to select a lower-reso- 
lution graphics mode. 

For example, using VGA graphics with a vertical resolution of 480 pixels, the 
graphics mouse cursor does not appear on screen, but when using the SetGraph- 
Mode(1) command to select medium resolution VGA graphics with a 350 vertical 
resolution, the mouse cursor does appear. If so, contact Microsoft, Logitech or your 
mouse supplier to obtain a new version mouse driver or purchase one of the new 
“HiRes” mice. With the Logitech mouse, mouse driver version 4.0 or later supports 
all VGA resolutions. 


Creating an Object-Mouse Unit 


The MOUSE.TPU unit (compiled from MOUSE.PAS) will be referenced by many 
of the programs in the book. The program listing for a unit begins with the unit 
heading: 


unit MOUSE; 


which simply identifies the unit name that will be employed by other programs in 
the uses clause to refer to the unit. The unit name must be unique and the compiled 
unit must have the same filename and use the extension .TPU. 

Following the unit declaration is the interface portion which declares constants, 
types, variables, procedures and functions that are public; they can be accessed by 
applications that use the unit: 


INTERFACE 


The type definitions declared by the unit are also available to the applications 
using the unit: 


type 
Position = record 
btnStat, 
opCount, 
xPos, yPos : integer; 
end; 
GCursor = record 


ScreenMask, 
CursorMask : array [0..15] of word; 
hotX, hotY : integer; 

end; 
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Two Buttons vs. Three 


The mouse unit provides compatibility for both two- and three-button mice, 
principally by providing definitions for all three buttons: 


Buttont. = 6; 
BUttOnNR 3.15 
ButtonM = 2; 


Note: if you have worked with OS/2-Presentation Manager, the mouse buttons 
are defined under OS/2 as 1-2-3, from left to right (with a system option to reverse 
the order for southpaws). Conventional mouse button ordering, however, began 
when computer mice had only two buttons, left and right, thus, the third (middle) 
button is out of order and is numbered 2. For two-button mice the third, middle, 
button is not available. 

Four other constants are provided for general use. The constants software and 
hardware are used to set the text cursor and Off and On are for general use in 
Boolean applications as the equivalent of True and False: 


Software = QO; 
Hardware = 1; 

OFF = False; 
ON = True; 
Graphics Mouse Cursors 


Five graphics cursors are predefined in the mouse unit for use with graphics mouse 
applications. The arrow cursor is an angled arrow similar to the default graphics 
cursor. The check cursor is a check mark with the hot-spot at the base of the angle. 
The cross cursor is a circle with crosshairs marking a centered hot-spot. The glove 
cursor is a hand image with the hot-spot at the tip of the extended index finger and, 
last, the ibeam cursor duplicates the popular vertical bar marker used with graphics 
text applications. The hot-spot for the glove cursor is centered roughly on the 
vertical bar. 

All of the graphics cursors are available to applications using the mouse unit 
and are defined as follows: 


arrow : GCursor = 
( ScreenMask : ( $S$1FFF, SOFFF, S$O7FF, SOSFF, 
SOI1FF, SOOFF, SOO7F, SOOSF, 
$OO1F, SOOSF, SOTFFE,): SOT, 
SEQFF, SFOFF, SFSFF, SFSFF ); 
CursorMask : ¢ $0000, $4000, $6000, $7000, 
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$7800, $7C00, $7E00, $7FOO, 

$7F80, $7C00, $4C00, $0600, 

$0600, $0300, $0300, $0000 ); 
notx =. $0001! hotY- ss: S000 | i: 


The MOUSEPTR program creates an ASCII text file following this same format 
and can be imported directly to any Turbo Pascal program listing or added to the 
MOUSE.PAS unit source listings. 


The Object Definitions 


The object definitions begin with a general mouse object type, GenMouse (General- 
Mouse), which contains two record variables—the x- and y-axis position coordi- 
nates—and 12 functions and procedures belonging to the GenMouse object: 


type 
GenMouse = object 
iS fe OTN Tecer : 
Visible : Boolean; 
function TestMouse: boolean; 
procedure SetAccel( threshold : integer ); 
procedure Show( Option : Boolean ); 
procedure GetPosition( var BtnStatus, 
XPos, YPos : integer ):3 

procedure QueryBtnDn( button : integer; 

Ver mouse s Position ) 
procedure QueryBtnUp( button : integer; 

Var mouse : Position )+: 
procedure ReadMove( var XMove, YMove : integer + 
procedure Reset( var Status : Boolean; 

var BtnCount : integer ); 
procedure SetRatio(€ horPix, verPix : integer ); 
procedure SetLimits( XMin, YMin, 
XMax, YMax : integer ); 
procedure SetPosition( XPos, YPos : integer ); 
end; 


The GenMouse object type is the base object type and contains functions and 
procedures that are common to all mouse objects. Four other object types, which 
will actually be used by applications, are declared. They begin with the Graphic- 
Mouse object type which adds three new procedures that are specific to graphics 
mouse applications: 


GraphicMouse = object( GenMouse ) 
procedure Initialize; 
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procedure ConditionalHide( left, top, right, 
bottom : integer ); 
procedure SetCursor( cursor : G€ursor 7; 
end; 


The TextMouse object type is also a descendant of the GenMouse type, adding 
two text specific procedures: 


TextMouse = object( GenMouse ) 

procedure Initialize; 
procedure SetCursor( ctype, C1 €2 : Werd-ay 
end; 


The final two object types are descended from the GraphicMouse object type 
and the TextMouse object type; each adding the LightPen procedure to support the 
rare, but still occasional, applications that require lightpen support for either 
graphics or text applications: 

GraphicLightPen = object GraphicMouse ) 


procedure LightPen( Option : Boolean ); 
end; 


TextLightPen = object( TextMouse ) 
procedure LightPen( Option : Boolean ); 
end; 


The Implementation Section 


The implementation section defines the body of the functions and procedures 
declared in the interface section. That is, the code specific to each procedure or 
function, and any types, constants, variables or local procedures or functions that 
are private—not directly available to the application using the unit: 


IMPLEMENTATION 
uses Crt, Dos, Graph; 


The unit itself can, and often must, reference other units as above. Since this 
uses statement appears within the IMPLEMENTATION section, the referenced 
units are not automatically available to the calling application: 


var 
Regs : registers, 
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The Regs variable is global to the procedures and functions in the unit, but it is 
not accessible to the application using the unit. Also, the two functions, Lower and 
Upper, are local functions and not accessible outside of the unit: 


function Lower( n1, n2 : integer ) : integer; 

begin 
if nt <= n2-then: Lower 
else Lower 


n1 
ne: 


end; 


a 


function; Upper Cont, n2 
begin 
if n1 > n2 then Upper 
else Upper 


nteger ) : integer; 


n1 
he; 


end; 


The GenMouse Implementation 


The GenMouse implementations begin with the function TestMouse which exe- 
cutes a simple test to determine if a mouse driver is presently in the system. This 
is not a substitute for the Reset function, and should only be used if there is a 
question about whether a driver has already been loaded. 


function GenMouse.TestMouse : Boolean; 


const 
iret = 207; 
var 
dOff, dSeg : integer; 
begin 
dOff := MemWCL0000:0204]; 
dSeg := MemWC0000:0206]; 


if€ « dSeg = 0) or € d€Of# =) 0°): 
then TestMouse := FALSE 
else TestMouse := MemECdSeg:dOff] <> iret; 
end; 


The Reset Function 


The Reset function calls the mouse driver, resetting the driver to default conditions 
and returning a mouse status argument in the AX register (—1 if mouse present, 0 
if not available). The argument is tested to provide a Boolean response. The BX 
register returns the button count (2 or 3) for the mouse: 


procedure GenMouse.Reset( var Status : Boolean; 
var BtnCount : integer ); 
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begin 
regs.AX := $00; 
intr C$33,reges; 


Status es rpegs.AX <> OQ; 
BtnCount := regs.BX; 

end; 

The SetLimits Function 


The SetLimits function establishes screen limits (in pixels) for the mouse movement. 
This is particularly important when using higher resolution graphics because the 
default limits may not include the entire screen and, if it does not, portions of the 
screen cannot be reached with the mouse. 

The GraphicMouse. Initialize procedure calls SetLimits with the 0, 0, GetMaxx, 
GetMaxY arguments, to ensure that the entire screen is accessible to the mouse, but 
other applications may request smaller screen limits. 

When restricting the mouse to a portion of the screen, if an application is using 
an exit button, as demonstrated in the MousePtr program, either ensure that an 
alternate exit procedure is supplied or that some method of reaching the exit button 
is always available: 


procedure GenMouse.SetLimits( XMin, YMin, 
XMax, YMax : integer ); 


begin 
regs.AX := $07; { horizontal Limits } 
regs.CX := Lower(XMin,XMax); 
regs.DX := Upper(XMin,XMax); 
intr($33,reoqs2- 
regs.AX := $08; { vertical Limits } 
regs.CX := Lower(YMin,YMax); 
regs.DX := Upper(YMin,YMax); 
intr($33,regs); 
end; 
The Show Function 


The Show function is used to turn the mouse cursor on and off by calling mouse 
functions 1 and 2, respectively. 

Any time a screen update is being executed in an area that includes the mouse 
cursor, the mouse cursor should be turned off before repainting the screen and then 
restored afterwards. Otherwise, the effects can be surprising, but not desirable. If 
you would like to see examples caused by omission, comment out the body of this 
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procedure and then run the MousePtr program (after recompiling the MOUSE.TPU 
unit): 


procedure GenMouse.Show( Option : Boolean ); 


begin 
if Option and not Visible then 
begin 
Visible := FALSE; 
regs.AX := $01 { show mouse cursor } 


intr(€$33,regs); 

end else 

if Visible and not Option then 
Visible := FALSE; 


regs.AX := $02; { hide mouse cursor } 
intr (C$33,regs); 

end; 

end; 


Conventional Mouse Functions Show and Hide 


The mouse pointer (cursor) can be turned on or off multiple times but, for example, 
if the mouse pointer is hidden three times in succession, a corresponding sequence 
of show operations will be required to make it visible again. Both operations 
increment or decrement a status counter. If the counter is zero or negative, the 
mouse cursor is hidden; if one or greater, the mouse cursor is visible. 

Note that hiding the mouse cursor does not affect tracking or button opera- 
tions—the mouse position is tracked even if the mouse is invisible. 


The SetPosition Function 


The SetPosition Function is used to move the mouse cursor to a specific location on 
the screen. The coordinates used are always absolute screen coordinates in pixels. 
In text modes, pixel coordinates are still used, but the coordinates are rounded off 
to position the cursor to the nearest character cell indicated by the pixel coordinates 
(for example with an 8x8 text display, x/y pixel coordinates of 80/25 would 
correspond to the 11th column and 4th row of the screen). 


procedure GenMouse.SetPosition( XPos, YPos : integer ); 
begin 


regs.AX := $04; 
regs.CxX = XPos; 
regs.DX := YPos; 


intr($33,regs); 
end; 
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The GetPosition Function 


The GetPosition function reports the mouse cursor position and the status of the 
mouse buttons. Position coordinates are always in pixels. 

BtnStatus is an integer value with the three least-significant bits indicating the 
current status of the left, right and, if present, middle buttons. The corresponding 
bits in BtnStatus (starting with bit 0) will be set if the button is down or clear if the 
button is up: 


procedure GenMouse.GetPosition( var BtnStatus, 
XPos, YPos : integer ); 
begin 
regs.AX := $03; 
intr($33,regs); 
BtnStatus := regs.BX; 


XPos = regs.CX; 
YPos = regs.DX; 
end; 


The QueryBtnDn Function 


The QueryBtnDn function reports the current status of all of the buttons, a count 
of the number of times the requested button has been pressed (since the last call to 
QueryBtnDn for this button), and the mouse coordinates when the requested 
button was last pressed: 


procedure GenMouse.QueryBtnDn( button : integer, 
var mouse : Position ); 
begin 
regs.AX := $05; 
regs.BX := button, 
intr($33,regs); 


mouse.btnStat := regs.AX; 
mouse.opCount = regs.BX; 
mouse.XxXPos = regs.CX; 
mouse.yPos = regs.DX; 
end; 
The QueryBtnUp Function 


The QueryBtnUp function is the equivalent of QueryBtnDn except for reporting 
the number of times the requested button was released: 


procedure GenMouse.QueryBtnUp( button : integer, 
var mouse : Position ); 
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begin 
regs.AX := $06; 
regs.BX := button; 
intrts3ss,regs);: 


mouse.btnStat := regs.AX; 
mouse.opCount := regs.BX; 
mouse.xPos = regs.CXx; 
mouse.yPos = regs.DX; 
end; 
The ReadMove Function 


The ReadMove function returns a total horizontal and vertical step count since the 
last call to the ReadMove function. For a normal mouse, the step count varies from 
a low of '/100 inch increments (100 mickeys/inch) for older mice to 1/200 inch (200 
mickeys/inch) for more modern mice and !/320 inch increments (320 mickeys/inch) 
for a HiRes mouse. 

Movement step counts are always within the range -32768..32767, a positive 
value indicating a left to right motion horizontally or, vertically, a motion towards 
the user (assuming the cable is pointed away from the user). Both horizontal and 
vertical step counts are reset to zero after this call: . 


procedure GenMouse.ReadMove( var XMove, YMove : integer ); 
begin 

regs.AX := $0OB> 

intr($33,regs); 

XMove := regs.Cx; 

YMove regs.DX; 
end; | 


Since the mouse graphics or text cursors are updated automatically, the Read- 
Move function is not required to control the screen presentation, but may be used 
for special applications. 

See also the SetRatio and SetAccel functions. 


The SetRatio Function 


The SetRatio function controls the ratio of physical mouse movement to screen 
cursor movement with the x- and y-axis arguments (horPix and verPix) expressed 
as the number of mickeys (units of mouse motion) required to cover eight pixels 
on the screen. Allowable values are 1 to 32767 mickeys, but the appropriate values 
are dependent on the number of mickeys per inch reported by the physical mouse: 
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values which may be 100, 200 or 320 mickeys per inch depending on the mouse 
hardware. 

Default values are 8 mickeys/8 pixels horizontal and 16 mickeys/8 pixels 
vertical. For a mouse reporting 200 mickeys/inch, this requires 3.2 inches horizon- 
tally and 2.0 inches vertically to cover a 640x200 pixel screen: 


procedure GenMouse.SetRatio( horPix, verPix : integer d's 
begin 


regs.AX := $OF; 
regs.CX := horPix,; { hor mickeys/pixel ratio } 
regs.DX := verPix; { ver mickeys/pixel ratio } 
intr ($33,regs? ; 

end; 

The SetAccel Function 


The SetAccel function establishes a threshold speed (in physical mouse velocity 
units, mickeys/second) above which the mouse driver adds an acceleration com- 
ponent, allowing fast movements with the mouse to move the cursor further than 
slow movements. 

The acceleration component varies according to the mouse driver installed. For 
some drivers, acceleration is a constant multiplier—usually a factor of two—while 
other drivers, including the Logitech mouse, use variable acceleration with multi- 
plier values increasing on an acceleration curve: 


procedure GenMouse.SetAccel( threshold : integer : a 
begin 


regs.AX := $13; 
regs.DX := threshold; 
intr($33,regs); 

end; 


The threshold value can be any value in the range 0..7FFFh with an average 
value in the range of 300 mickeys/second. Acceleration can be disabled by setting 
a high threshold (7FFFh) or restored by setting a low or zero threshold. 


The GraphicsMouse Implementation 


The GraphicsMouse implementation adds three graphics-specific functions to the 
general mouse functions inherited from the GenMouse object type. 
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The SetCursor Function 


The SetCursor function loads a new cursor screen and mask, making it the active 
graphics mouse pointer: 


procedure GraphicMouse.SetCursor( cursor : SCursor.2d2 
begin 


regs.AX := $09; 

regs.BX := cursor.hotx; 

regs.CX := cursor.hoty; 

regs.ES := Seg( cursor.ScreenMask ) 


regs.DX := Ofs( cursor.ScreenMask a3 
intr($33,regs); 
end; 


The selected graphics cursor may be one of the predefined cursors supplied 
with the mouse unit (MOUSE.TPU) or may be a cursor defined by the application 
program. 


The ConditionalHide Function 


The ConditionalHide function designates part of a rectangular area of the screen 
where the mouse cursor will automatically be hidden and is used principally to 
guard an area of the screen that will be repainted: 


procedure GraphicMouse.ConditionalHide( 
left, top, right, bottom : integer ); 


begin 
regs.AX := $10; 
regs.CxX s= left; 
regs.0X s= top; 
regs.$I s= rights 


regs.DI : bottom; 
intr($33,regs); 
end; 


The mouse cursor is automatically hidden if it is in or moves into the area 
designated, but the ConditionalHide function is temporary; functioning by 
decrementing the mouse counter in the same manner as a call to the Show(FALSE) 
function. 

The area set by calling ConditionalHide will be cleared and the mouse cursor 
enabled over the entire screen by calling Show(TRUE). 
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The Initialize Function 


The Initialize function is created as a convenience for setting up the graphics mouse 
operations and accomplishes four tasks: enabling the mouse to cover the entire 
graphics screen (recommended), setting the default mouse cursor (optional), cen- 
tering the cursor on the screen (optional), and calling Show to make the mouse 
cursor visible: 


procedure GraphicMouse.Initialize,; 

begin 
Visible := FALSE; 
SetLimits( 0, 0, GetMaxX, GetMaxY ); 
SetCursor( arrow ); 
SetPosition( GetMaxX div 2, GetMaxY div 2 i} 
Show( ON ); 

end; 


The TextMouse Implementation 


While three functions were added to create a graphics mouse object descended from 
the general mouse object, to do the same for the text mouse, two procedures are 
provided. They parallel two of the graphic mouse procedures: Initialize, a function 
setting initial conditions for the text mouse and SetCursor, a function for setting the 
text cursor type. 

While these two functions have the same names as the GraphicMouse func- 
tions, each is implemented in an entirely different manner. Strictly speaking, 
however, this is not an example of polymorphism because both the GraphicMouse 
and TextMouse are descended from GeneralMouse and not from each other (these 
are siblings, not descendants). 


The Initialize Function 


Like its GraphicMouse counterpart, the TextMouse. Initialize function begins by 
setting the Boolean variable Visible as False. 

To establish limits for the mouse movement, the SetLimits function is called 
with values retrieved from the Crt unit, containing the minimum and maximum 
window settings. Since WindMin and WindMax are word values and contain both 
x- and y-window (character) coordinates, the lo and hi functions are used to return 
individual values that are converted to pixel coordinates: 


procedure TextMouse.Initialize; 
begin 
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Visible := FALSE; 
SetLimits(€ Lo(WindMin)*8, hiCWindMin)*8, 
LoCWindMax)*8, hi€CWindMax) *8 a 
SetCursor(€ Hardware, 6, 7 ); 
setPosttion( 0,0); 
Show(€ TRUE ); 
end; 


Finally, the text cursor is set to a hardware underline cursor and Show is called 
to make the cursor visible. 


The SetCursor Function 


The text version of the SetCursor function can be used to select either hardware or 
software cursor: 


procedure TextMouse.SetCursor( ctype, ¢1, ce: word 3+ 
begin 


regs.AX := SOA: 
regs.BX := cType; { O = software / 1 = hardware } 
regs .Cx 32 es { screen mask or scan start } 
regs.0X := c2; { cursor mask or ten stop :3 
intr($33,regs); 

end; 


The hardware cursor uses the video controller to create the cursor with the 
arguments (cl and c2) identifying the start and stop scan lines for the cursor. The 
number of scan lines in a character cell is determined by the hardware video 
controller (and monitor), but as a general rule, for monochrome systems the range 
is 0..7 and for CGA the range is 0..14, top to bottom. 

In general, however, a start scan line of six and a stop scan line of seven will 
produce an underline cursor. A start scan line of two and a stop scan line of five or 
six produces a block cursor and works well even on high resolution VGA systems. 

The software cursor is slightly more complicated. Using the software cursor, 
the cl and c2 parameters create a character or character attributes which are, 
respectively, ANDed and XORed with the existing screen character. 

The cl parameter (screen mask) is ANDed with the existing screen character 
and attributes at the mouse cursor location, determining which elements are 
preserved. Next, the c2 parameter (cursor mask) is XORed with the results of the 
previous operation, determining which characteristics are changed. 

In actual practice, a screen mask value of $7F00 might be used to preserve the 
color attributes, while a cursor mask value of $8018 would establish a blinking 
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up-arrow cursor or $0018 for a non-blinking up arrow. In either case the existing 
foreground and background color attributes are preserved. In the same fashion, a 
screen mask of $0000 and a cursor mask of $FFFF will produce a flashing white 
block cursor. See Table 29-1 for more information. 


Table 29-1: Software Cursor Parameter Format 


Bit Description 

0..7 Extended ASCII character code 
8..10 Foreground color 

11 Intensity: 1 = high, 0 = medium 
12..14 Background color 

15 Blinking (1) or non-blinking (0) 


As a general rule, the eight least-significant bits of the screen mask should be 
either $..00 or $..FF; with the former preferred. 


The LightPen Implementation 


While lightpens are relatively scarce, a few applications do continue to use these, 
and the mouse driver package offers a pair of functions supporting lightpen 
emulation. 

Because these are rarely needed, two descendant object types have been cre- 
ated—one descended from the TextMouse and the other from the GraphicMouse 
object types. Both implement the lightpen functions in exactly the same manner: 


procedure TextLightPen.LightPen( Option : Boolean ); 
begin 
if Option then regs.AX 
else regs.AX 
intr($33,regs); 
end; 


$0D { turn pen on } 
SOE; { turn pen off } 


procedure GraphicLightPen.LightPen( Option : Boolean ); 
begin 
if Option then regs.AX 
else regs.AX 
intr($33,regs); 
end; 


$O0D { turn pen on } 
SOE 2 { turn pen off } 


Lightpen emulation is turned off by default. When enabled, simultaneous 
down states of both the right and left buttons emulate the pen-down state and 
release of both buttons emulates the pen-up state. 
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The Mouse Pointer Utility 


A mouse cursor editor (MOUSEPTR.PAS) is the second example in this chapter (see 
Figure 29-1); a program providing both a useful utility to create mouse cursor 
images and a means of demonstrating the use of the mouse unit. 

While MOUSEPTR could have been created as an object-oriented program, this 
utility is written largely in conventional Pascal format, aside from calls to the 
object-oriented mouse unit. This is done for two reasons: first, to avoid complicating 
the utility itself and, second, because portions of the code used in this program will 
serve to contrast the object-oriented graphics button structures to be created in 
Chapter 30. 

You are, however, welcome and invited to practice object-oriented program- 
ming by revising the MOUSEPTR program using the object-oriented button utili- 
ties that will be presented shortly. 

The MOUSEPTR program is generally self-explanatory and provides two grid 
structures for editing the screen and cursor masks to create a mouse pointer image. 
Naturally, editing is accomplished using the mouse to toggle squares in the grids 
or to select the option buttons below the grids. In brief, the options listed in Tables 
29-2 and 29-3 are provided: 


Table 29-2: Option Buttons 


Cursor Mask Options Description 


Clear Reset all bits in the cursor mask grid to FALSE (zero). 
Invert Reverse all bits in the cursor mask grid. 
Copy to Screen Copies the cursor mask grid to the screen mask grid. 


The .CUR File Format 


The mouse cursor image is saved in an ASCII format that is suitable for direct 
inclusion in any program. It is included by using the MOUSE.TPU unit: 


const 
arrow : GCursor 
€ ScreenMask : ( $1FFF, SOFFF, SO7FF, SO3FF, 
SO1FF, S$OOFF, SOO7F, S$OO3F, 
S$OO3F, $003F, SO1TFF, SOOFF, 
SEOFF, SFOFF, SFOFF, SFOFF ); 
CursorMask : (€ $0000, $4000, $6000, $7000, 
$7800, $7C00, $7E00, $7F00, 
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$7F80, $7C00, $4C00, $0CO00, 
$0600, $0600, $0600, $0000 ); 
hotX : $0001; hotY : $0001 ); 


The control options affect both the screen and cursor masks. 

All values are written in hexadecimal format, simplifying any manual editing 
or revising that might be desired. The hotX and hotY values are written as word 
values though these are actually only integer values (and never exceed $000F). 
Conversion is handled automatically by Turbo Pascal. 


Table 29-3: Screen Mask Options 


Screen Mask Options Description 

Clear Reset all bits in the screen mask grid to FALSE (zero). 
Invert Reverse all bits in the screen mask grid. 

Make from Cursor Creates a screen mask grid image from the cursor mask 


grid—for each point in the screen mask grid, if the corre- 
sponding point in the cursor mask grid or any adjacent 
point in the cursor mask grid is TRUE, the screen mask 
grid point is FALSE. 


Hot Spot The next point selected in either the screen or cursor mask 
grids will be the hot-spot for the mouse cursor and will 
appear in red on both grids. Any existing hot-spot is 


cleared. 

Use Pointer Makes the edited cursor image the active mouse pointer on 
the screen. 

Arrow Pointer Restores the arrow mouse pointer. 

Load Pointer Requests a filename to load a saved cursor image. Must be 


an ASCII file in the same general format as created by this 
program. The extension .CUR and current directory are 
assumed. 


Save Pointer Saves the current screen and cursor grid images to an 
ASCII file using hexadecimal format. The output file can be 
imported directly for use by any Turbo Pascal program. 
The current directory is used and the filename extension 
.CUR is automatically supplied. 


Exit Exits from the program—no safety features are supplied to 
prevent accidental exits. 
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Figure 29-1: The Mouse Cursor Editor 











Screen Mask Cursor Mask 


Soeeee IIe 
coememee te} 
Soemenenee EI} 
Gotmmememee! it i i te 
Somemimcememan | if ji 
Guemememamememee! jt | i} 


Ee ieeemenememmnee i Ho it i} 
oT ea | a 
Gitimmememesener It ti 
eee I 
LIC eee I) 
Lt eee IC) 
CH i eee it 





Conventional Style Button Operations 


The MousePtr utility is operated by the series of button controls listed previously, 
but these are buttons only in a limited sense. An outline and label are written to the 
screen with a separate function arbitrarily matching the mouse pointer location 
coordinates at the time that a mouse button is pressed to the corresponding screen 
images. The screen and cursor grids are treated in a similar fashion. 

In Chapter 30, this dichotomy will be resolved in an object type named Button. 
Also, image, screen positions and control responses will be merged into a single 
control object. 

The Button object type could be used to replace a large part of the programming 
instructions in the MousePtr utility program, replacing not only the screen, cursor 
and general control buttons, but also replacing the screen and cursor grids with 
arrays of blank buttons. 

For the moment, however, the topic is the conventional or non-object-oriented 
control structure that begins by using the GMouse object (type GraphicMouse) to 
enable graphics mouse operations: 


GMouse.Reset( mStatus, Buttons ); 
if mStatus then 
begin 
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SetWriteMode( CopyPut ); 
GMouse. Initialize; 


with GMouse do 
repeat 


Instead of specifying the GMouse object for every operation within the repeat 
loop, the instruction with GMouse do simplifies the programmer’s task. Within the 
loop, only the left mouse button is used and the loop begins by calling QueryBtnDn 
to test for a left button pressed event: 


QueryBtnDnC( ButtonL, 
if mButton.opCount > O then 


begin 


mButton ); 


If the returned opCount is not zero, the next step is to decide where the mouse 
cursor was located when the button was pressed. This is accomplished with nested 


case statements. 


case mButton.yPos of 


503,420 


{ screen or cursor grids } 


case mButton.xPos of 


{ screen mask } 12 
{ set hotspot } 279 


{ cursor mask } 384 


(stoo 
ixooe 


on Be4 


ScreenSet( mButton ); 
if mButton.yPos >= 250 
then SetHotSpot; 
CursorSet( mButton ); 


end; { case mButton.xPos } 


280..300 


{ screen or cursor commands } 


case mButton.xPos of 


ce ss 
33. 
s fm ee 


364. 
494. 
564. 


ae oe 
Tess 
Jevat 


.484: 
a eee 
624 


{ screen mask items } 


ClearScreen; { Cisar 2 
InvertScreen; { Invert } 
ScreenFromCursor; { Make } 
{ cursor mask items } 
CursorToScreen; { Copy ; 
InvertCursor; { Invert } 
ClearCursor; { Clear } 


end; { case mButton.XPos } 


320..340 


{ general command options } 


case mButton.xPos of 


Las 
140. 
265. 
S90. 
a 15. 


end; ¢f 


shew s 
weous 
Yat S 
~s00: 
~b23% 
case 


UseNewCursor; { Use } 
SetCursor( arrow ); 

LoadPointer,; { Load } 
SavePointer; { Save } 


Exit := TRUE? 
mButton.xPos } 


end; {( case mButton.yPos } 
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end; 
UNTIL Extt; 


While this response structure does work well, it has a serious deficiency. A 
popular adage holds that “if it works, don’t fix it!” But sometimes what works in 
one situation does not work in all situations. The coding used in this example is a 
case in point. For an EGA or higher resolution graphics system, the MOUSEPTR 
program works just fine, but, for a CGA video, extensive conversions would have 
to be made before the image grids and the control buttons could fit within a 
200-pixel vertical resolution. 

While it would be possible to write formulas to provide adaptation to different 
vertical (and horizontal) resolutions for the screen images, it would also be neces- 
sary to have a series of variables associated with each of these screen elements and 
to assign screen coordinate values to each corresponding to the video resolution in 
use. In conventional programming, however, this is awkward and unwieldy. This 
is also one point where object-oriented programming provides tremendous advan- 
tages, see Chapter 30. 

The remainder of the MousePtr.PAS program is generally self-explanatory and 
appears in the listings at the end of this chapter. 


Summary 


In this chapter, an object-mouse was created to be compiled as a unit— 
Mouse. T'PU—and will be used in later examples to provide general mouse control. 
Before proceeding further, you should have a working mouse unit, containing both 
the graphics and text mouse object methods, compiled and ready for use. 

Either the MousePtr program or the demo programs in Chapter 30 can be used 
to test the object-mouse unit: 


(=ss=SSSSSSSe522SSeeeee==2==} 
{ MOUSE.PAS } 
{ mouse object with both } 
{ text and graphic vers } 
(s=ssS25SsSs2S5e25525e22=====} 

C{S$O+, F+} 

unit MOUSE; 

interface 

type 

Position = record 


BtnStatus, opCount, xPos, yPos : word; 
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end; 

EventRec = record 

Event, BtnStatus, XPos, YPos : word, 
end; 
record 

ScreenMask, 

CursorMask : array CO..15] of word; 
hotX, het Y 2 -titeger; 
end; 


GCursor 


var 
mEvent : EventRec; 


const 

ButtonL = QO; 

ButtonR = 1; 

ButtonM = 2; 

Software = 0O; 

Hardware = 1; 

OFF = False; 

ON = True; 
(=sSSSSSSeSSeeseeseSSesssssssssesssesa=} 
{ five graphics cursors are predefined } 
{ for use with GraphicMouse } 
| ee ee, 

arrow : GCursor = { default graphics cursor } 


( ScreenMask : ( S$1FFF, SOFFF, S$O7FF, SOSFF, 
SO1FF, SOOFF, SOO7F, SOOSF, 
SOOTF, SOOSF, SOTFF,-SUTFKF, 
SEOFF, SFOFF, SFSFF, SFBFF ); 
CursorMask : ¢€ $0000, $4000, $6000, $7000, 
$7800, $7C00, $7E00, $7FOO, 
$7F80, $7C00, $4C00, $0600, 
$0600, $0300, $0300, $0000 ); 
hotX : $0001; hotY : $0001 ); 


check : GCursor = { check mark graphics cursor } 
( ScreenMask : (€ SFFFO, $FFEO, SFFCO, SFF81, 
$FFO3, $0607, SOOOF, SOO'IF, 
$803F, SCO7F, SEQFF, SEFIFF, 
SFFFF, SFFFF, SFFFF, SFFFF 0; 
CursorMask : ¢ $0000, $0006, $000C, $0018, 
$0030, $0060, $70C0, $3980, 
$1F00, $0E00, $0400, $0000, 
$0000, $0000, $0000, $0000 ); 
hotX 3: S00CS; hotyY : $0070.27 
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cross: .: GCursor =.= { circle with cross hairs } 
€ ScreenMask : (€ SFOI1F, $EOOF, $CO07, $8003, 
$0441, $0C61, $0381, $0381, 
$0381, $0061, $0441, $8003, 
$CO07, SEOOF, SFOIF, SFFFF ); 
CursorMask : (€ $0000, $07C0, $0920, $1110, 
$2108, $4004, $4004, $783C, 
$4004, $4004, $2108, $1110, 
$0920, $07C0, $0000, $0000 ); 
ROCK ¢ SQOOT? hoty +: SO0G7 >: 


glove : GCursor = { glove or hand image cursor } 
( screenMask : € SFSFF, SETFF, SETFF, SETFF, 
SE1FF, $E049, $E000, $8000, 
$0000, $0000, $O7FC, $07F8, 
SOFFO, S8FF1, $C003, $E007 ); 
CursorMask : (€ $0C00, $1200, $1200, $1200, 
$1200, $13B6, $1249, $7249, 
$9249, $9001, $9001, $8001, 
$4002, $4002, $2004, $1FF8 ); 
hotX ; $0004; hotY : $0000 ); 


ibeam : GCursor = { I-beam cursor } 
( ScreenMask : (€ $E10F, SEOOF, $F83F, SFC7F, 
SECT, StCrtty Steri, SFCVF, 
SrCrE, SECTE, SECTE, SECT, 
SFC7F, S$FSSF, SEOOF, $E10F » 
CursorMask : (€ $0000, $0C60, $0280, $0100, 
$0100, $0100, $0100, $0100, 
$0100, $0100, $0100, $0100, 
$0100, $0280, $0C60, $0000 ); 
Nnoth..3 $0007;  hot¥: $0007 3; 


type 
GenMouse = object 

Xy ¥ 2S: Dateger ; 
visible : Boolean; 
function TestMouse: boolean; 
procedure SetAccel( threshold : integer be 
procedure Show Option : Boolean ); 
procedure InstallTask( Mask : word ); 


procedure ClearEvent; 
procedure GetPosition( var BtnStatus, 
XPos, YPos : integer ); 
procedure QueryBtnDn( button : integer; 
Ver mouse +. Position > 
procedure QueryBtnUp( button : integer; 


var mouse 


procedure ReadMove( var XMove, 


procedure Reset( var Status 


var BtnCount 
verPix =: 


procedure SetRatio(€ horPix, 


procedure SetLimits( XPosMin, 
XPosMax, 


procedure SetPosition( XPos, 
end; 


GraphicMouse = object( GenMouse 
procedure Initialize; 


procedure ConditionalHide( left, 
right, 
procedure SetCursor(¢ cursor 
end; 
TextMouse = object( GenMouse ) 


procedure Initialize; 
procedure SetCursor( ctype, 
end; 


GraphicLightPen = object( GraphicMouse ) 
Boolean ); 


procedure LightPen( Option : 
end; 


YPosMax 
YPos 


) 
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Position: 2% 
c.3nteger 2; 
Boolean; 


YMove 


top, 
bottom 


integer ); 


integer ); 
YPosMin, 


GCursor ); 


Ci, 


TextLightPen = object( TextMouse ) 


procedure LightPen( Option 
end; 


implementation 
uses Crt, Graph, Dos; 


var 
Regs : registers; 


function Lower( ni, n2 : integer ) 
begin 
if ni < n2 then Lower := n1 
else Lower Nes 


end; 
nteger ) 


_ 


function Upper( ni, né 
begin 
if ni > n2 then Upper 
else Upper 


n1 
nes 


end; 

procedure MouseHandler( Flags, CS, 
Si. 

interrupt; 

begin 


Ce 


integer ); 
integer ); 


integer ); 


word J; 


Boolean ); 


integer; 


{ 


: integer; 


3 oe 
DI, 


AX, 
DS, 


{ 


BX, 
ES, 


Local function } 


Local function } 


CX, OX, 
BPs word 7; 
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mEvent.Event = AX; 
mEvent.BtnStatus = BX; 
mEvent.xPos = CXS 
mEvent.yPos = DX; 
{ exit processing for far return to driver } 
asm 
mov sp,bp 
pop bp 
pop es 
pop ds 
pop di 
pop”) si 
pop dx 
pop cx 
pop bx 
pop ax 
retf 
end; 
end; 
(S=SSSSSSSSs55Ss52555eSSSSSSee5eeeeee====2=} 
{ implementation methods for GeneralMouse } 
(SSSSSS55SSS5SS55SSS55eeeeeSe5eeeeeee======} 
function GenMouse.TestMouse : Boolean; 
const 
TCEt: 2-207? 
var 
dO0ff, dSeg : integer; 
begin 
dOff := MemWCL0000:0204]; 
dSeg := MemWC0000:0206]; 


14h £3 gseqg =: 0 ) or: € dott = 0-3) > 
then TestMouse FALSE 
else TestMouse MemECdSeg:dOffl] <> iret; 


end; 


procedure GenMouse.Reset( var Status : Boolean; 
var BtnCount : integer ); 


begin 
regs.AX := $00; { reset to default conditions } 
intert: 233, rege :)3 
Status >= regs.AX <> OQ; { mouse present } 
BtnCount := regs.BX; {" putton count <3 
end; 


procedure GenMouse.SetAccel( threshold : integer ); 
begin 
regs.AX := $13; 
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regs.DX := threshold; 
intr( $33, regs ); 


end; 
procedure GenMouse.Show( Option : Boolean ); 
begin 

if Option and not Visible then 

begin 


regs.AX := $01; { show mouse cursor } 
Visible := TRUE; 
intr( $33, regs 7; 
end else 
if Visible and not Option then 
begin 
regs.AX := $02; { hide mouse cursor } 
Visible := FALSE; 
intrt $33,. regs i; 


end; 
end; 
procedure GenMouse.GetPosition( var BtnStatus, 
XPos, YPos : integer ); 
begin 
regs.AX := $03; 


intr( $33, regs ); 
BtnStatus := regs.BX; 


XPos = regs.CX; 
YPos >= regs.DX; 
end; 


procedure GenMouse.SetPosition( XPos, YPos : integer ); 
begin 


regs.AX := $04; 

regs.CX := XPos; 

regs.DX := YPos; 

intr( $33, regs ); 
end; 


procedure GenMouse.SetRatio( horPix, verPix : integer ); 
begin 
regs.AX := SOF; 


regs.CX := horPt?x; { horizontal ratio } 
regs.DX := verPix; { vertical ratio } 
intr( $33, reqs’ 2; 

end; 


procedure GenMouse.QueryBtnDn( button : integer; 
var mouse : Position ); 
begin 
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$05; { function O5h } 
button; 
intrt S335, regs > 


regs.AX 
regs.BxX 


7 
mouse.BtnStatus = regs.AX; 
mouse.opCount >= regs.BX; 
mouse.xPos = regs.CX; 
mouse.yPos = regs.DX; 


end; 


procedure GenMouse.QueryBtnUp( button : integer; 
var mouse : Position ); 


begin 

regs.AX := $06; 

regs.ex := button; 

intre £33, regs): 
mouse.BtnStatus := regs.AX; 
mouse.opCount = regs.BX; 
mouse.xPos = regs.CXx; 
mouse.yPos = regs.DX; 


end; 


procedure GenMouse.SetLimits( XPosMin, YPosMin, 
XPosMax, YPosMax: integer); 


begin 
regs.AX := $07; { nRertzontal Uimits 3 
regs.CX := Lower( XPosMin, XPosMax ); 
regs.DX := Upper( XPosMin, XPosMax ); 
intr( $33, regs ); 
regs.AX := $08; { Vertical ttwits 3} 
regs.CX := Lower( YPosMin, YPosMax ); 
regs.DX := Upper(€ YPosMin, YPosMax ); 
intr e235, regs ds 
end; 


procedure GenMouse.ReadMove( var XMove, YMove : integer ); 
begin 

regs.AX := $0B; 

intr € $33, regs ); 

XMove := regs.CXx; 

YMove := regs.DX; 


end; 
procedure GenMouse.InstallTask; 
begin 
regs.AX := $0B; 
regs .CX ¢= Mesk; 
regs.DX := ofs(€ MouseHandler ); 
regs.ES := seg( MouseHandler ); 


intr( $33, regs ); 
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end; 
procedure GenMouse.ClearEvent, 
begin 
mEvent.Event := 0; 
end; 
ee 
{ implementation method for GraphicsMouse } 
(22S HSSSSSSaea SSeS SSSsSeesssssssessssssa} 
procedure GraphicMouse.SetCursor( cursor : GCursor ) 3 
begin 
regs.AX := $09; { function OQ9h } 
regs.BX := cursor.hotX,; 
regs.CX := cursor.hotyY; 
regs.DX := Ofs( cursor.ScreenMask : 
regs.ES := Seg cursor.ScreenMask ); 
intr( $33, regs 25 
end; 


procedure GraphicMouse.ConditionalHide( 
Left, top, right, bottom : integer ); 


begin 
regs.AX := $0A; { function OAh } 
regs.CX := left; 
regs.DX := top; 
regs.SI := right; 
regs.DI := bottom; 
intr¢( $33, regs 2; 
end; 


procedure GraphicMouse.Initialize; 

begin 
Visible := FALSE; 
SetLimits( 0, 0, GetMaxX, GetMaxY ); 
SetCursor( arrow ); 
SetPosition( GetMaxX div 2, GetMaxY div 2 ); 
Show( TRUE ); 


end; 
ee, 
{ implementation method for TextMouse } 
(==SSSSSSSSSSSSeSSeesesesssssssssses==} 

procedure TextMouse.Initialize; 

begin 


Visible := FALSE; 

SetLimits( lLo€ WindMin )*8, hi€ WindMin )*8, 
Lo( WindMax )*8, hi€ WindMax )*8 ); 

SetCursor( Hardware, 6, 7 ); 
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setPosttion( 0, 0 ): 
Show(€ TRUE ); 
end; 


procedure TextMouse.SetCursor( ctype, Ct, ¢2 4 werd: 3: 
begin 


regs.AX := $OA; { tunetion 10h > 
regs.BX := ctype; { 0 = software, 1 = hardware } 
fFegs.Ck <¢s ct; { screen mask or scan start line } 
rPegs.0X% := ¢2; { cursor mask or scan stop line } 
intr€ $33, regs ); 
end; 
(==SSSSSSSSSS5S55S2sSeSeSeSSeeee5e=======} 
{ implementation method for TextLightPen } 
(==SsSSSSSS5S555555555S55555S5555=5======} 
procedure TextLightPen.LightPen( Option : Boolean 3 
begin 
if Option then regs.AX := $0OD {turn pen. on} 
else regs.AX := $OE; c:- turn pen off 3} 
intet S33, regs): 
end; 
(SSSSSS55S5SSS5555555555S5S5555e5525S2ee=====} 
{ implementation method for GraphicsLightPen } 
(==SSSSSSSSSS55555555555SSSS55e5e525S2=======} 
procedure GraphicLightPen.LightPen( Option : Boolean » 
begin 
if Option then regs.AX := $0D +: -tGPAn pen on. 3 
else regs.AX := $OE; { turn pen off } 


intrt $33, regs ): 


end; 
end of: unit } 
end. 
(==SSS5SSS555552222S55555552======} 
{ MousePtr.PAS } 
{ utility to create new graphic } 
{ mouse cursors and demonstrate } 
{ graphic mouse object operation } 
(=SSSSSS555SS52525555555S5=5==2===} 
C$F+} 
uses Crt, Graph, Mouse; 
type 
STR20 = stringl20]; 
STR12 = stringl(12]; 
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var 
GMouse : GraphicMouse; 
TMouse : TextMouse,; 
mButton . Post tion; 


NewCursor : GCursor; 

GDriver, GMode, GError, i, j, Buttons, 

XIndex, YIndex, HotSpotX, HotSpotyY : integer; 

Exit, HotSpotSelect, MStatus : Boolean; 

Screen, Cursor : arraylO..15,0..15] of Boolean; 
outline : ‘arraylts.51 of PointType; 

Ch « crar; 


procedure BoxItem( x, y, W, h : integer; text : STR20 ); 
begin 

SetTextJustify( CenterText, CenterText ); 

Rectangle( x, y, xtw, yth ); 

OutTextXY( x+tOw div 2), ytCh div 2), text ); 
end; 


procedure FillSquare( x1, y1, Key Wee 
FillStyle, Color : integer ); 


var 
outline : arrayLl1..5] of PointType, 
begin 
outlLineC1].x := x1; outlinelLil.y := yl; 
outlineL2].x := x2; outlinel2].y := yl; 
outlLineC31.x := x2; outlinel3].y := y2; 
outlLinel[4].x := x1; outlinel4l.y := y2; 


outline£5] := outlineli]; 
SetFillStyle( FillStyle, Color ); 
FiLLPoly( sizeofCoutline) div sizeof( PointType ), 
outline ); 
end; 


procedure EraseSquare( x1, y1, x2, y2 : integer re 
var 

i, j : Integer; 
begin 

FitLSquere€ x1, yl, X2, Yer SolidFItl, BLACK I; 
end; 


procedure Beep, 
begin 
Sound( 220 ); delay( 100 ); NoSound; 
delay (¢ 50.) 
Sound( 440 ); delay( 100 ) 
end; 


=e “Sse & 


NoSound; 


function StrToHex( WorkStr: string ): word; 
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var 
TempVal 
begin 
TempVal 
for4 
begin 
TempVal TempVal shl 4; 
case WorkStrlidJd of 
Wes e eee nee TeémevV at, 
Ae PTs tne) Tenevat, 
end; {case} 
end; 
StrToHex 
end; 


word; 


$0000; 


= 1 to lLength(WorkStr) 


TempVal; 


function HexToStr( NumVal word 
const 
HexStr 
var 
Temp string(4i; 
CVal byte; 
i : integer; 


'0123456789ABCDEF'; 


begin 
Temp := ‘ 
TOF 4 44 
begin 
CVal 
NumVal 
Temp 
end; 
HexToStr 
end; 


_ —_— t . 
7 


to 4.-do 


( NumVal and $0O00F 
NumVal shr 4; 
copy( HexStr, CVal, 


Temp; 


procedure MakeCursor; 
var 
1303 
TBit 
begin 
with NewCursor do 
begin 
hotxX 
hotyY 
tor 4 
begin 
ScreenMaskLiJ 
CursorMaskLiJ 
end; 


integer; 
word; 


HotSpotx; 
HotSpoty:; 
Oto" 45 ds 


$0000; 
$0000; 


do 
ord(€ WorkStrlil] ) - $30 ); 
ord€ WorkStrlid ) - $37 ); 
a2 String: 

BR aay 

1) + Temp; 
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for %.:@.@. -¢e 45. do 
begin 
TBit := $0001; 
Tor.3 33-0 ¢96.- 79 do 
begin 
CursorMaskCiJ := CursorMaskLCild shl 1; 
1f. Cursortj,-14-then: inet CursorQMaskEts.); 
ScreenMaskCil] := ScreenMaskCiJd shl 1; 
if Sereenti,1ti then ifftet SereenMaskCid >; 
end; 
end; 
end; 
end; 


procedure UseNewCursor; 

begin 
MakeCursor; 
GMouse.Show( FALSE ); 
GMouse.SetCursor( NewCursor ); 
GMouse.Show( TRUE ); 


end; 
procedure PaintScreen( X, Y : integer ); 
var 
Color : tnteger; 
begin 


if ¢€ X = HotSpotx,) and ¢€ Y = HotSpoty ) 
then Color := LIGHTRED 
else Color := WHITE; 
GMouse.Show( FALSE ); 
if Secreenlx, Yd tien 
FillLSquare€ (€X4#1)¥154+5, CY¥+2)*15+5, 
CX#2)*15-3, CY4+3)*15-5, 
Sotigrrtt. icecaer> 
else 
FillSquare€ (X+#1)*15, CY+2)*15, 
CX+2)*15, CY+3)*15, 
CLoseDotFill, WHITE 2; 
GMouse.Show( TRUE ); 
SetColor( WHITE )>; 


end; 
procedure PaintCursor( X, Y : integer ); 
var 
Color : integer; 
begin 


if ( X = HotSpotxX )- end ©. Y= Hotspot? 2 
then Color := LIGHTRED 


570 


end 


pro 
var 


beg 


end 


pro 
var 


beg 
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else Color := WHITE; 
GMouse.Show( FALSE ); 
1f Cursor tx, YI. then 
FillSquare( (X+1)*15+369, CY+2)*15, 
CX42)*154566, CY#3)715-5, 
SOLAGETEC? beter > 
else 
FillSquare( (X+1)*154+369, CY+2)*15, 
CX#2)%*154369, CY¥*+3)*15, 
WidedotFitt, Colter: 
GMouse.Show( TRUE ); 
SetColor( WHITE ); 


/ 

cedure HotSpotComplete; 
p Gia: ae ate A aa ee a 

in 


X s= HOtSootx; 
Y -s= Hotspoty; 


PaintcCursor( X, Y 33 
Paerntsereent X, ¥d3 
GMouse.Show( FALSE ); 
HotSpotSelect := FALSE; 


Settoteort WHITE >: 

SetTextJustify( CenterText, CenterText ); 
BoxItem( ave, 230, 8G, 20, "R#6tsau0t*. v3 
GMouse.Show( TRUE ); 

Ys 


cedure SetHotSpot; 


Ka oe SR teger: 
in 

X := HotSpotx; 

Y 3:8 Hotspoty> 
HotSpotxX := -1; 
HotSpotY := <1; 
PaintCursor¢. XxX, Y 
PaintScreen( X, Y ); 
GMouse.Show( FALSE ); 
HotSpotSelect := TRUE; 
SetCotor(€ RED ); 
SetTextJustify(€ CenterText, CenterText ); 
BoxItem( e193, 290, ee: £00. MAnepotrt. 2: 
SetColor( WHITE ); 

GMouse.Show( TRUE ); 


3 
) 
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end; 
procedure ScreenLayout; 
var 
j : integer; 
begin 


j := GetMaxXx; 
SetTextJustify( CenterText, CenterText ); 
Out TextxY¢ 135, 20, ‘'Sereen: Bask’ >; 
OutTextxXY¥¢ 504, 20, 'Curser Basek* d; 
HotSpotComplete; 
{ screen mask items } 
BoxItem( 15, €80,- 663 267 5%€teer* 2: 
Boxitem( 85, 280, 605. 20, *Tnvert’ >: 
Boxitem( 155, 280, 140, 20, ‘Make from Cursor® )+3 
| { cursor mask items } 
Boxitem( 564, 280, 60,205: Cieer*. 2; 
Boxitem( 494, 280, 60, 205.-,4nvert.’ 2; 
BoxiItem( 344, 280, 140, 20, ‘Copy: to Screen’ ); 
{ control options } 
BoxItem( 745, 320, 110, 20, *888- Fe inter* «zz 
Boxitem(. 140, 320, 110, 20, “Arrow FPetnmter. a 
Boxitem( 265, 320, 110, 20, ‘Lowed FPointer* +72 
Boxltem( 390, S20, P4303 20),° "Seve Pointer’ 3 
Boxltent 515, 3205-1883) 4s 7 Sete". Fs 


end; 
procedure ClearScreen; 
var 

ta 3.2 Integer, 
begin 


for 7 2:2 0 to 15 do 
for {| == @ to 15 do 
if Screenli,j] then 
begin 
ScreenLi,ji 2:2 FALSE: 
PaintsereenGoty. 2: 


end; 
end; 
procedure ClearCursor; 
var 
i, } & thHteger; 
begin 


for 4+ = © te-23 86 
Tor j- t= GO te -13 Go 
1f Cursorli,ij2 then 
begin 
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Cursorli,jds:2 FALSE; 
PetntCursert$ 3,0 3° 24 


end; 
end; 
procedure InvertScreen; 
var 
toc s aeteper: 
begin 


Tart eae te) 4S) hoe 
fer.:). 42:0) to 15° do 
begin | 
Screenli,jJ := not Screenli,jd; 
PaintScreen( 1, 9°33 
end; 
end; 


procedure InvertCursor; 
var 
te.) one eoer > 
begin 
T6F: 7:4 O 46.75 as 
Tor S28" 0 “40. 13 (40 
begin 
Cursort[i,~jjJ t= not Cursorlyt, jd: 
Patntcursor¢:. i, ° 30 33 
end; 
end; 


procedure ScreenSet( mButton : Position ); 
var 
X, Vv 2. 3ntecers: 
begin 
x := mButton.xPos div 1 
y := mButton.yPos div 1 
if HotSpotSelect then 
begin 
HotSpotxX x3 
HOZSpPOTY := yy; 
HotSpotComplete; 
end else 
begin 
ScreenlCx,yl] := not Screenlx,yJ]J; 
ParntsSere@ent x, ¥ 33 7 
end; 
end; 


5 13 
5-=- 23 


procedure CursorSet( mButton : Position ); 
var 
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Xo YF tHEeGtrs 
begin 
x ( mButton.xPos - 384 ) div 15; 
wi mButton.yPos div 15 —- 2; 
if HotSpotSelect then 


begin 
HotSpetX := x2 
HOtSpOtY += ¥ 5 


HotSpotComplete; 
end else Cursor€x,yld := not €ursortix,yd; 
PaintCursort x, y 2; 


end; 
procedure CursorToScreen; 
var 
is J ¢ Integer, 
begin 


for 1 s= 0: $0.73 60 
far j{ 3:2 0 So) T3:€0 
begin 
Screenli,j] := Cursertt,123 
PaintSereent i, 3 2: 
end; 
end; 


procedure ScreenFromCursor,; 
var 
L, Io Ry -¥°2 THteger? 
Test : boolean; 
begin 
for + :® 0 €o6°43: Bo 
for j := 0 to 73 Go 


begin 
Test := TRUE; 
for x == -—] t0 1 do 


for y t= -1 to +f Go 
1t¢ tx on €0..152 2. and 
pry. in £0,454 .2 ere 
Cursorlitx,jtryd then Test := FALSE; 
Screenli,i2 += test: 
PaintScreent: +,°° } #3 
end; 
end; 
function GetFileName( var FileName: Stri2; 
Prompt: string ): boolean; 


var 
1°: -THte~geT; 
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Ch os CRA 2 
Done : Boolean; 


begin 
{om Be 
Done := FALSE; 


PT CONS Cie eee 0. wtecece ie 
SetViewPort¢t 269, 0, 369, 42,3 TRUE D5 
SetTextJustify( CenterText, CenterText ); 
GMouse.SetCursor( ibeam ); 
repeat 
He t4 2s 
GMouse.Show( FALSE ); 
ClearViewPort; 
SetColor(€ LightRed ); 
Rectangie( 0,0, 100, 40.32 
OutTextxYy<( 50, 10, Prompt. .2; 
OutTextxz7< 30, 20, “Five: Nene? 25 
OutTextxY( 50, 30, FileName); 
GMouse.Show( TRUE ); 
GMouse.SetPosition( 285+1*8,30 ); 
repeat until KeyPressed; 
Ch := ReadKey; 
case Ch of 


#S0D : Done :© TRUE; 
Wee <TC ee TS Bae Sect 12° 2 2 
A ping ty 
' | 
tA 
A eA 
aaa ee ek A ee 2 een 
begin 
Beep; 


Geet 7, 1-2:3 
end else FileNameLild := UpCase(C(Ch); 

end; {case} 
until Done; 
GMouse.SetCursor( arrow ); 
GMouse.Show( FALSE ); 
ClearViewPort; 
GMouse.Show( TRUE ); 
for i := 8 downto 1 do 


TTL FP enamel te) oor: te Pipe taenet $3 a: te!) 
then FileNamelOJ] := chr(i-1); 
if FileName = '' then GetFileName := False else 
begin 


FileName := FileName+'.CUR'; 
GetFileName := True; 
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end; 
SetViewPort( 0, 0, GetMaxX, GetMaxY, TRUE ); 
end; 
procedure SavePointer; 
var 
+ : tnteger: 
Ch : char; 
Cr F Tex 
FileName STHRi1¢? 
begin 
MakeCursor; 
if GetFileName( FileName, 'Save as' ) then 
begin 
Assign( CF, FileName ); 
Rewrite( CF ); 
writein’s Gry “*“csonst"?: 
write ( Cre * ' + 
copy ¢ Length(FileName)-4 ) ); 


FileName, 1, 
wri tetet tr. ° GCursor ='); 
with NewCursor do 
begin 
writeln( CF, '€ ScreenMask 
HexToStr(€ScreenMaskl0OJ]), 
HexToStr(ScreenMask([11]), 
HexToStr(ScreenMask[2]), 
HexToStr(ScreenMaskl31]), 
Tor 1 £2 1 t£0 3 do 
begin 


write<¢ GF, *S"*sd2, 


HexToStr(ScreenMaskLi*4 


Fea e285 
JF $', 
nae 
Oe a 
a ); 


J), ae $', 


HexToStr(ScreenMaskli*4+1J), ', $', 
HexToStr(ScreenMaskLli*4+2]), ', $', 
HexToStr(ScreenMaskli*4+3]) ); 


at ££. SD MAS MOTHS Cr, te 
etee: Wrttetne: Cr, * dy * D3 
end; 
writeln( CF, 'CursorMask S322, 
HexTostrtCursorMaskCGJ), *, S$, 
HexToStrttursorWaskiti2, *,° 3" 
HexToStrtCCursorMaskE2i), ‘, $° 
HexToStrtCursorMaskl3J),.'3° ba 


for 4 22°-4 to 3: @c 
begin 


ertvtet Chy * Ssee5 


HexToStr(CursorMaskLli*4 


1), "9 S$‘, 


HexToStrCCursorMaskli*4é4#+1J), ‘', $‘', 
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HexToStrCeursorhaskts*4¥ei), ‘*, 3", 
HexToStr(CursorMaskli*4+3]) ); 
E44 eS COR WP VE OLN CRB ret) 


elee  wWritetnt CF, hore dg 
end; 
WTO VA CRs I ReOte 2: 6 Ete, HExToOStrthots), 
Po SY Se NeSTeOStT rt hott)... 5 32" 2s 
end; 


weFtTetnt CF 2; 
CtoseC CF. 23 
end else Beep; 
end; 


procedure LoadPointer; 
var 
1g See ee TA eer 2 
FileName : STR12; 
WorkText <4. strings 
TempVal - word: 
OF 8° Cage: 


begin 

2 ee ae & 

if GetFileName( FileName, ‘Load from' ) then 

begin 
Assign( CF, FileName ); 
{$I-} Reset( CF ); {$I +} 
eh SVK esutrt = 0: 2- then 
begin 


ClearScreen; 
ClearCursor; 
repeat 
readln( CF, WorkText ); 
if Pos('$',WorkText) > O then 
TOP} 35-7 tec 4- ee 
begin 
while WorkTextl1J <> '$' do 
delete(WorkText,1,1); 
delete(WorkText,1,1); 
TempVal := StrToHex(copy(WorkText,1,4)); 
case i of 
DO. whos. FOr Kees t6e. 15.00 


begin 
if (TempVal and $8000) <> O then 
begin 


Screenlk,41) :=) TRUE; 
PaintScreen(k,1); 
end; 
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TempVal := TempVal shl 1; 
end; 
T6Oc4018 Tor kh 287 8. Boc 4s" Sey 
begin 
if€TempVal and $8000) <> QO 
then Cursorlk,i-16] := TRUE; 
PaintCursor(k,i-16); 
TempVal := TempVal shl 1; 
end; 
32: HotSpotX := TempVal; 
33: begin 
HotSpotY := TempVal; 
PaintCursor( HotSpotxX, HetSpotyY ): 
PaintScreen( HotSpotxX, HotSpoty ); 


: oe co { break out of Loop } 
end; 
end; {case} 
met + 29 
end; 
untit 1 > SS} 
Close( CF ); 
end else Beep; 
end else Beep; 
end; 
begin 
HotSpotX := OQ; { default settings for hotspot } 
HotSpotY := 0O; { upper left corner of matrix } 


7 
GDriver := Detect; 
InitGraph(€ GDriver, GMode, '\TP\BGI' ); 
SetGraphModeC 1 ); 
GError := GraphResult; 
if GError <> grOk: then 
begin 
writeln(€'Graphics error: ‘, GraphErrorMsg( GError ) ); 
writetnC' program eborted..«.«° 3 
Nalttt?; 
end; 
ClearDevice; 
Exit :s= FALSE; 
ScreenLayout; 
tor 4° ye-o £6. 75. ve 
Tor: + =2,/0 to 15 es 
begin 
Screenli,3J 
Curserts i) 
end; 


TRUE; 
TRUE; 
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ClearCursor; 
ClearScreen; 
GMouse.Reset( mStatu 
if mStatus then 
begin 
SetWriteMode( 


with GMouse do 
repeat 
QueryBtnDnC( Bu 


CopyPut 
GMouse. Initialize; 








6, But tone +23 


7 


7 


ttonL, mButton ); 


if mButton.opCount > O then 


case mButton.y 
50,4270 
case 
TDs 
ere. 


mButto 
s255 
oo? 


384. 
end; 
vou 
case Reuse 
3 ea 
85..145 
ASO se wae 
364..484 
494..554 
564.4624: 2 
end; { case 
320..340 
case 
ee 
140. 
£65. 
390. 


~-624 
{ case 
280. 


mButto 
ote 
~250 
wots 
.500 
= i ee US | 
end; { case 
end; € case mB 
untTL Exits 
end; 
TMouse.Reset( mStatu 
TMouse.SetCursor( ha 
Beep; 
end. 


Pos of 
{ screen 
n.xPos of 


ScreenSet( mButton ); 

if mButton.yPos >= 250 
SetHotSpot; 

CursorSet( mButton ); 


mButton.xPos } 

{ screen or 
n.xPos of 
ClearScreen; 
InvertScreen; 
ScreenFromCursor; 
CursorToScreen; 
InvertCursor; 
ClearCursor; 
mButton.XPos } 

{ general 
n.xPos of 
UseNewCursor; 
SetCursor( arrow ); 
LoadPointer; 
SavePointer; 

Exit :=. TRUE; 
mButton.xPos } 
utton.yPos } 


Buttons ); 
ji a ay ae 


S; 
rdware, 


or: cursor grids >} 


then 


cursor commands } 


command options } 


Chapter 30 


Object Button Controls 


By itself, the object mouse created in Chapter 29 is interesting, but useless until 
applied to a practical task. The next step is, therefore, to create two types of control 
objects, Buttons and TBoxes, that respond to mouse hit events; and to create a 
simple demo program, BtnTest, to show how these control objects work. Before 
going into details on the creation of these two object types, I’ll begin with an 
overview of the operations of each. 


Graphics and Text Button Operations 


While the graphics and text button operations are provided as independent units, 
there are similarities between the two object types. Examples of the text button 
objects appear in Figure 30-1 and the graphics button objects appear in Figure 30-2. 

For both object types, several elements are assigned when each object instance 
is created. For the text buttons, the parameters include the outline type, size, 
position, color and text label. For text buttons, the box outline is created using the 
extended ASCII character set and may be a single, double or blank outline. For 
graphic buttons, the button style may be Square, Rounded or ThreeD. 

For text buttons, only the horizontal size (in columns) is selected, with the 
vertical size fixed at three rows. For graphics buttons, both vertical and horizontal 
sizes are set (in pixels) and, if the vertical size is greater than the horizontal, the text 
orientation is set as vertical. 


579 
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Both the text and graphics buttons accept string arguments for the text label, 
but the handling is slightly different in each case. For the text button, the label is 
truncated if it will not fit within the button outline. For the graphics button, labels 
are also truncated if necessary, but first, the typeface is sized and reduced as 
necessary to find the best fit for the label within the button. As you can see in Figure 
30-3, even after selecting a smaller font size, the label has still been truncated in 
some instances. 

Position arguments are accepted by both button types. For the text buttons the 
coordinates are row/column positions and, for the graphic buttons they are pixel 
positions; both setting the upper left corner positions. 


Figure 30-1: Text Button Images 


Se eee Renee teeeeeeeeeercesssurerrectcceceseserecrsseseersm 
Pee eee eee tee ee east eee e saat acetaateeeeesaateneeme 


AVesssceeseesncersrersssessecersecessseeeessrenssrecseed? 
PhESTitititititiititii tits iiiitietiiititititittititiisy 





ioe ox = 





eS 





QUIT Test Box 5S | 


This is a Text Button demonstration 


Text Button States and Colors 


Foreground and background colors are also assigned when each instance of the 
object is created. In this implementation, however, the assigned background color 
is used immediately, but the foreground color is used only when the text button’s 
state is set as Select. Initially, each text button is set as Off and must be explicitly 
changed to Select—either by the program or by mouse-selection—before the 
assigned color will be used for highlighting. In the default Off state, the button is 
drawn using the LightGray color. 

A third text button state, Invalid (shown in Figure 30-1), is also provided. This 
causes the button to be drawn using the DarkGray color. This particular provision 
is often useful when an option should be shown but is not, in the present circum- 
stances, selectable. 
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Figure 30-2: Graphic Button Images 





Graphic Button States and Colors 


For the graphics button objects, only two states are provided—True or False—and 
no Invalid state is implemented. As before, a default state of False is assigned when 
the button is created and must be explicitly changed. 

The graphic buttons differ from the text buttons in another respect: the graphic 
button images are always drawn using the assigned color and, for highlighting to 
show selection, the background and foreground colors are swapped (button 3 in 
Figure 30-2) and the buttons are redrawn. 


Button Mouse Selection 


Both the text (TBoxes) and graphic (Buttons) button objects have provisions to 
recognize mouse hits, but in the current programs, neither object type tests the 
mouse position or interrogates mouse button events directly. Instead, the applica- 
tion program must watch for mouse button events, passing the event coordinates 
to each instance of the object for testing. 

When the object detects a mouse hit, by comparing the event coordinates with 
its own position and size, a boolean hit result is returned to the application program. 
Either the text or graphics object button automatically changes its own state and 
redisplays itself accordingly. 
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In the present demo, the tests and responses are limited. The only mouse button 
tested is a left-button down event and, when the left button is pressed, the first 
response is to test all of the text or graphic buttons. If any are set as Select then the 
button’s Invert procedure is called to turn it off. After all screen buttons have been 
reset, a second loop polls each of the screen buttons for a mouse hit. If the mouse 
button event did coincide with a screen button, the screen button turns itself on and 
the application program responds with an audible prompt. 

If a text button with the Invalid state set is mouse-selected, the only result is an 
audio prompt generated by the button object—not by the application. 


The TBoxes Unit 


The TBoxes unit is the first control object created. This provides a text-oriented 
object type displaying a box outline and text label (see Figure 30-1). TBoxes begins 
by declaring the two data types: 

type 


BoxStete.= ¢ Off, Gelect,::Iinvat td. as 
BoxType = ( None, Single, Double ); 


In this case, the object type Box is not created as a descendant of any other object 
type: 
Box = object 
%, -¥ Cotor, BackColor, B41 26X%. 3% -integer: 
Exist : boolean; 
State : BoxState; 
ThisBox : BoxType; 
BtnTxt te STROC: 
The Box object has several variables shown, most are self-explanatory. The 
Boolean variable, Exist, however, deserves a few comments and a few cautions. 


The Exist Variable 
In the demo program, BtnTest, two arrays of objects are declared as: 


GButton : arrayli1..101 of Button: 
TBUtten:- 2s arreyl1..10) oF 86x32 


Because these are object-type variables, they are often expected to carry out 
semi-independent operations, but if the variable has not been initialized, the 
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operations executed can be surprising at best and, at worst, may cause a system 
hang-up. 

In the demo programs used in this book, there is little chance for a declared, 
but uninitialized object to be called. I prefer to err on the side of safety. In the 
application programs, after declaring an array of object, the Exist variables for all 
elements in the array are declared as False by calling the Initialize method: 


for 1 «= 1 ‘to 10. de 

begin 
GButtonlild.Initialize; 
TButtonlid Initialize; 

end; 


Many of the critical methods in the object do not execute unless the Exist 
variable has been set to True. This is done when the Create method is called for each 
object type. 

If you examine the source code for each of these objects, you will note that more 
than the Exist flag is affected by the Initialize method. Also, the Box.Initialize 
method is more elaborate than the Button. Initialize method. In either case, the Exist 
flag setting is the primary objective of the Initialize method, while the remaining 
method code is either optionally redundant or might be handled equally well by 
the object’s Create method. 

To return to the purpose, using the graphic button object as an example, 
suppose that a nonexistent button is called by any of several instructions, resulting 
in the Draw method being called. If the button size has not been assigned by a call 
to the Create method, it could result in an extremely long wait while graphics 
operations are attempted over an indeterminate area or, in other cases, a system 
hang-up may be the result (see Table 30-1). 


Table 30-1: Random Results Returned by Six Uncreated Buttons 


Width Height Exist 

Width = 1024 Height = 0 Exist = True 
Width = 191 Height = 7680 Exist = True 
Width = -24240 Height = 0 Exist = False 
Width = 232 Height = -30464 Exist = True 
Width = 30464 Height = 24044 Exist = True 


Width = -442 Height = -4983 Exist = True 
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In the worst case shown the size of the button object is 30,464 by 24,044—a total 
of 732,476,416 pixels; over 3,000 times the size of the average screen. Drawing or 
erasing an image of this size can take a bit longer than expected, or worse, 
operations may extend to critical memory locations, disrupting the system. 
Another method of preventing such accidents; using constructor and destructor 
calls and dynamic allocation, will be demonstrated later. 


Box Object Methods 


Nineteen methods are declared for the object-type Box, most are self-explanatory. 
A few of these, however, deserve at least a brief mention. 

The Create method for the text button, accepts arguments setting the initial 
position, size, foreground and background colors, and text label for a text button 
object. The Create procedure sets Exist as True for the current instance, ensures that 
the text string will fit within the declared size and finally, calls the Draw method to 
create a text button on the screen. No position tests are provided, but if they are 
desired, they would be better implemented in the Draw method than here in the 
Create method. 

The Initialize method requires no arguments, but resets all variables to zeros 
or to False, clearing the object instance for further use. No screen operations are 
executed. 

The DrawBox method is the heart of the Box object, writing the text button 
screen image: 


procedure Box.DrawBox; 


var 
BoxStr +i atrinelé6s> 
1, RPos, YPos +: integer: 
OLaAttr 3. word: 

begin 
XPos := WhereXx; 
YPos := WhereY; 
OldAttr := TextAttr; 


Since the text buttons are intended for use with applications that will have other 
text material on screen, before a button is created, the current screen attributes and 
cursor position are saved and will be restored before the DrawBox method is 
completed. 

The current text color is determined by the button’s State and the button’s 
assigned background color: 


Chapter 30: Object Button Controls 585 


case State of 
Off : TextCotlord LiaghtGray: 2; 
Select : TextCcotort Color 2; 
Invalid : TextColor( DarkGray ); 
end; {case} 
TextBackground( BackColor ); 


Next, the local variable, BoxStr, is given the characters appropriate to the 
assigned box style: 


case ThisBox of 
None: BoxStr 
Single: BoxStr 
Double: BoxStr 
end; { case } 


; 
HSDA+HSBF+HSCOFHSDIO+HSC4+H$B3; 
HECO+HSBB+HSCBE+HSBC+HSCD+HSBA; 


At this point, all that’s left is to write the screen image: 


sotoxy< %,-¥. 22 { tep of box 7 
write€ BoxStrliJd ); 

for + 3:3 2 to Sitzex=? do writet BoxStrlsJ 2) 

write( BoxStrl2J]); 

gotoxy( x, yt J; { center of box } 
write( BoxStrl6] ); 

for 4 28 2 te. Sitget-i do wreitec! ‘2, 

write( BoxStrl6] ); 


The interior of the box is written as spaces to clear anything that might already 
appear on the screen, then the new label is written, centered. 


gotoxy( x + € SizeX-ord(BtnTxtCO]) ) div 2, yt I); 

write( BtnTxt ); 

eotexyt x, ye «2; { bottom of box } 
write( BoxStrl3J] ); 

for 1.12 2° to Sizex-1 do. writet BoxStrtsi-37 

write( BoxStrl4] ); 


Finally, the saved cursor position and screen attributes are restored, leaving the 
system ready for other operations. 


TextAttr t= GLGATt rr; { restore colors } 
gotoxy( XPos, YPos ); { restore position } 
end; 


One more method deserves explanation. The BoxHit method which is called 
by the application with two parameters that give the coordinates of a mouse button 
event and returning a boolean result: 
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function Box.BoxHit( MouseX, MouseY: integer ): boolean; 
var 


Result : boolean; 
begin 
MouseX MouseX div 8 + 1; 


MouseY := MouseY div 8 + 1; 


Because the coordinates reported by the mouse event are in pixel units, the 
MouseX and MouseY parameters are converted to character positions (row/col- 
umn units) before testing: 


Result := False; 
if€ MouseX >= x ) and ( MouseX < x+SizeX ) and 
( MouseY >= y ) and ( MouseY <= y+2 ) then 
Result trues 


If the reported coordinates fall within the button object’s parameters (i.e., Result 
is True), then the BoxHit method calls the Invert method to show that the button 
has been hit; finally returning Result to the calling application: 


if Result then Invert; 
BoxHit := Result; 
end; 


The remaining 15 methods used by the Box object can be found in the program 
listings at the end of this chapter. Quite a few methods are provided but not utilized 
by the demo program. Remember, any methods that are not used by an application 
are not included by Turbo Pascal in the compiled program. Nothing is saved by 
being skimpy about declaring methods. 


The Buttons Unit 


The Buttons unit is the graphics parallel of the TBoxes unit; providing graphic 
button images that can be tested for mouse event hits, responding with a visual 
queue as well as returning a boolean result. 

Note, however, that the methods provided for the text and graphic button 
features are only approximately parallel and the graphic buttons differ from the 
text buttons in two principal respects: buttons may be any size (within the limits of 
the screen or window) and the button caption may be oriented vertically instead 
of horizontally. 

A variety of graphic button examples appear in Figure 30-3 in varying sizes, 
styles and orientations with button #5 (ThreeD-style) showing the selected state. 
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Notice also that buttons #1 and #2 are actually too small to properly display 
labels, but attempt to do so anyway. The demo generating the illustration in Figure 
30-3 used Borland’s TriplexFont that is sometimes too large for many applications. 
The SmallFont (LITT.CHR) provides an alternate stroked character font that is 
approximately half the size of the triplex font and, in general, more useful for small 
button labels. For more details on Borland’s fonts and sizing examples, refer to 
Graphics Programming In Turbo Pascal 5.5, Addison-Wesley Publishing Company, 
1988. 


Figure 30-3; Assorted Graphics Buttons 





Depending on your application, you may prefer to modify the Buttons unit to 
use this smaller font, or to adapt the label sizing algorithm to switch fonts for 
smaller labels. 

As can be seen in Figure 30-3, button labels are oriented vertically any time the 
button image is taller (in pixel units) than it is wide. This is an optional feature, and 
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the graphics button unit could be redesigned for closer similarities to the text 
buttons, but if the vertical orientation is eliminated, the revision should probably 
include restrictions on button height. 

Like the text version, the graphic buttons are established by calling the Create 
method but the parameter list is different in one respect: Button.Create is called as: 


procedure Create( PtX, ARF 
WTCGTtAS, HEIGKt;, (C:'3: Thteger: 
FEM E22 STRSO 22 


Unlike the text version, no explicit background color is assigned, but a width 
parameter is required. 

Like the text button version, the Create method is primarily concerned with 
assigning values derived from the calling parameters before calling the Draw 
method to execute the actual screen operations. One difference, however, is the 
boolean Rotate variable that is set by testing the width against the height: 


begin 
SetViewPort( 0, 0, GetMaxX, GetMaxY, ClipOn ); 
SetTextJustify( CenterText, CenterText ); 
x 28. PCA? 
y {a2 FGT: 
SizeX := Width; 
SizeY' s:= Height; 
if Sizex < 20 then Sizex 20; 
if. Siz2eT:. <:.20> then Sizey = é0 5 
1%¢ $1 20¥ >. S32eexX 2: then Rotate 


= True 
else Rotate := False; 
Color = C3 
State = False; 
Exist = True; 
BtnTxt = Text; 
Draw; 
end; 


The Draw method for the graphics buttons is somewhat more complicated than 
the text counterpart. It begins with two constants, radius and offset, that are used 
for the rounded corners and in order to control the fill area: 


procedure Button.Draw; 


const 
radius = 6; 
offset = 3; 
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The RectArr variable is an array of PointType (coordinate pairs) used to fill a 
rectangular outline: 


var 
RectArr : RectOutline; 
AlLignX, AlignY, TempSize, TextLen, 
i, BtnWd, BtnHt, Textdir.< integer ; 
begin 


The Draw method begins by setting a viewport (a graphics window) to the 
button size and further graphics drawing operations will be restricted to the 
viewport limits: 


SetViewPort( x, vy, **Si 20x, yrSizeY, Clipon 2); 
Graph.SetColor<t cotor 23 


A case statement that uses the Style variable, selects the appropriate drawing 
routines. It begins with the simplest case of the Square style: 


case Style of 
Square: 
begin 
Granh Rectengiet 0,. 0, Sizex, -StzeY ); 
BtnWd := Sizex - 10; 
Stnht 2S “§tzey - -t0;z 
end; 


For the Square style, the local variables, BtnWd and BtnHt, are set 10 pixels 
smaller than the button outline for later use in sizing the text label. 

The ThreeD style is next and begins by drawing the outer rectangle and filling 
the entire rectangle with using the CloseDotFill pattern: 


ThreeD: 
begin 
Graph.Rectangle( 0, QO, Sizex, SizeY ); 
SetOutline( RectArr, 1, ty -Stz98ex-1, Sizey-1)>; 
SetFiltlStytet Closedotk tel; eater. >> 
SetLineStyle( UserBitLn, O, NormWidth ); 
FillLPoly(€ sizeof(€RectArr) div 
sizeofCPointType), RectArr dD; 


On top of the dot-filled rectangle, the next step is drawing the inner rectangle 
and the four diagonal lines defining the sloped corner edges of the button: 


SetLineStyle( Solidtin,..@, Normwidth 2: 
Graph.Rectangle( 2*radius, 2*radius, 
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Line (¢ 
Line ( 
Line 
Line ( 


BtnwWd 
BtnHt 
end; 


0, 0, 
B33 


SizeX-2*radius, 


2*radius, 
ZeVY,:-é" radius, 
Sizex, 0, Sizex-2*radius, 


Sizex, SitzeY; 


SizexX-2*radius, 
Sizex-4*radius; 
SizeY-4*radius; 


SizeY-2*radius ); 


2*radius ); 
SizeY-2*radius ); 
2*radius ); 


SizeY-2*radius ); 


Finally, the BtnWd and BtnHt variables are sized smaller than the outer rectan- 
ele, again for use in later sizing the text label. 
If you are running the demo program BtnTest.PAS while reading this text, you 
may wish to change line 25 in BtnTest.PAS from SetButtonType( ThreeD ) to 
SetButtonType( Rounded ) to view this button style. 
The default style, Rounded, is the most complex of the three button styles and 
begins by drawing three quarter-circle arcs at the corner positions for the button 


image: 


else 

begin 
Style 
Graph 
Graph 
Graph 
Graph 


>= Rounded; 


Ar ot 
-Arc( 
aye on & 
~Arc¢ 


SizeX-radius, 


radius, radius, 


radius, SizeY-radius, 
SizeX-radius, 


270, 30U; 


ragi1ue; - 0, 


90, 60; 


radius ); 


90> padtus d: 
rediue:.i22 


[eu peruse TaGtus. 27 
SizeY-radius, 


After the corners are drawn, the straight sides are drawn connecting the ends 


of the arcs: 


Graph 


Graph 
BtnwWwd 
BtnHt 
end; 
end; { case 


ine < 
Graph. 
Graph. 


Line(¢ 
Line(¢ 


.Line(¢ 


radius, 
radius, 


Sizex, 


O, SizeX-radius, O ); 
SizeX-radius, SizeY ); 
0, radtus, OO; -Stzrey=radius >: 


SizeY, 


radius, 


:= SizeX-2*radius; 


} 


SizeY-2*radius; 


SizeXx, 


SizeY-radius ); 


Again, the final step is defining the BtnWd and BtnHt variables to later size the 


text label. 


The SetOutline subprocedure is provided to simplify assigning coordinate 
points to the RectArr structure with slightly different coordinates used for the 
Square or Rounded and ThreeD styles: 
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case Style of 
Square, 
Rounded: 
Setoutlinet RectaArr, offset, offset; 
Sizex-offset, SizeY-offset ); 
ThreeD: 
SetOutline(€ RectArr, 2*radiust1, 2*radiustl, 
SizeX-2*radius-1,SizeY-2*radius); 
end; {€ case } 

After the RectArr structure is set, a fill style is selected to show the button state, 
using a solid fill for a selected button or a wide dot pattern for a button that is off: 
‘* State then SetFittSstyviet SolidFitl, eotor 9 

else SetFillStyle(€ WideDotFill, color ); 
SetLineStyle( UserBitLn, O, NormWidth ); 
FILLPoly( sizeofCRectArr) div sizeof(PointType), 
RectaArr. 3 

Finally, the RectArr structure is passed to the FillPoly procedure to fill the 
interior of the button with the selected pattern. 

Now, the text label needs to be written, but first, the font size and string length 
have to be adjusted to fit the available space: 

SetLineStyle(€ SolidLn, O, NormWidth ); 
{ adjust fonts and string to fit } 
TempSize := FontSize; 
TextDir := HorizDir; 
if Rotate then 


begin { vertical text display } 
TextDir := VertDir; 
TextLen := BtnWd; 
BtnWd := BtnHt; 
BtnHt = TextLen; 


end; 
SetTextStyle( TypeFace, TextDir, TempSize ); 

Before changing the type size or truncating the string, the Rotate flag is tested 
and, if necessary, the label width and height are swapped (using TextLen as a 
convenient temporary variable). Finally, the text style is set as vertical or horizontal. 

Now, the font size—which begins large—is reduced until it either fits the 
vertical character space (BtnHt) or the size multiplier reaches one: 
for i := FontSize downto 1 do 

if€ TextWidth(BtnTxt) > BtnWd ) 


then SetTextStyle( TypeFace, TextDir, i ) 
else 
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if€ TextHeight(BtnTxt) > BtnHt ) 
then SetTextStyle( TypeFace, TextDir, i ); 


As long as the text size for BtnTxt is too large, each time the loop cycles, a new 
font size is set and tested on the next loop. The final loop, when the font multiplier 
reaches one, is not tested. If the text is still too large, the label is written anyway 
(see Button 2 in Figure 3-3). 

Finally, the text length is tested for fit and the string is truncated if necessary. 
Since the text will be displayed with centered alignment, any trail space is also 
truncated: 


TextLen := ord( BtnTxtLlOJ] ); 
while€ TextWidth(copy(BtnTxt,1,TextLen))>BtnWd ) do 
dec(€ TextLen ); 
if BtnTxtCTextLen] = ' ' then dec( TextLen ); 
if State then Graph.SetColor( GetBkColor ); 


If the button State is True—the button has been written as a solid field; the 
background color is selected before drawing the text. 


Required Unit References 


If the instruction, if State then Graph.SetColor(..., is written without the explicit 
reference to the Graph unit, a conflict will occur and, instead of the graphic SetColor 
procedure being called, the object’s own SetColor method will be called. In turn, it 
will recursively call the Draw method, which will call the SetColor method, which, 
will result in a closed loop hang-up. 

In this case, the conflict could have been prevented by not giving the object 
method a name that conflicts with an existing procedure in the Graph unit. Instead, 
the Button.SetColor method might have been better named as SetButtonColor. This 
conflict has been left in place, however, to illustrate a potential problem. 

There is also hope for such an error because omitting the explicit unit identifi- 
cation (Graph.xxx) will produce a stack overload (after about two minutes— 
depending on your CPU clock) and this will break you out of the loop. For purposes 
of instruction, the experiment is highly recommended. 

Warnings aside, the remaining step is to draw the text label. Afterwards, if 
necessary, the drawing color is reset and the viewport is reset to the full screen: 


OutTextxY( AlignX, AlignY, copy(BtnTxt,1,TextLen)); 
1f State then Graph.SetColor( color ); 
SetViewPort( 0, O, GetMaxX, GetMaxY, ClipOn ); 

end; 
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The remaining methods provided for the Buttons unit are self-explanatory, pro- 
viding inquiries for various button parameters or options to change parameters for an 
existing button without having to explicitly erase one button and create another. 


The Button Test Program 

The button test program (BtnTest.PAS) is a simple demo utility that creates first a 
text and then a graphic button display (see Figures 30-1 and 30-2), using the mouse 
unit created in Chapter 29 as the control I/O. If your system lacks a mouse, a 
keyboard mouse emulator can be created as a substitute. 

Five Pascal units are required: Crt, Graph, Mouse, Buttons and TBoxes; of which 
the latter three must be compiled to disk before the button test demo can be executed. 

The button test demo begins with the graphics buttons display, but, if when 
you execute the program, the graphics mouse cursor does not appear, you may 
have a problem that was mentioned in Chapter 29—a high resolution monitor and 
a low resolution mouse driver. If so, a one line revision (shown below) should reset 
the graphics driver to a resolution that is compatible with the mouse driver: 
GDriver := Detect; 

InitGraph(€ GDriver, GMode, '\TP\BGI' );3 
SetGraphMode( 1 ); { for low-res mouse drivers } 
GError := GraphResult; 

For a long term solution, the mouse driver may be upgraded—with or without 
purchasing a Hi-Res Mouse. Contact Microsoft, Logitech or your mouse manufac- 
turer for details. If this does not work, you might simply comment out the graphics 
portion of the demonstration and proceed directly with the text button demo. 

The Btn Test program itself should require no special explanations. 


Summary 

With the mouse object unit created in the previous chapter, the basics of control 
button operations were demonstrated using the text and graphics button objects. 
At the same time, a couple of potential problems were mentioned: uninitiated 
objects and duplicate method/ procedure names. 

The first potential problem was the case of calling an uninitiated object. In many 
cases, depending on the object type defined, this may not be a problem. In other 
cases, this can be an annoyance or possibly a disaster. Remember, it is bad program- 
ming practice. The practice of providing a boolean flag for each object type was 
suggested, with the flags for all elements of an array of object initialized as false 
until each instance of the object has been assigned values for any critical variables. 
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The second potential problem was the conflict of duplicate method / procedure 
names where both an object’s method and a procedure external to the object were 
given the same name and calling parameter arrangement—with a relatively safe 
experiment suggested to demonstrate one aspect of such a conflict. 


{SseseeSeeeSeeSseeeessseseseszrsesz} 
{ Buttons.PAS } 
{ creates Button object unit } 
{asmeseseseseeresssessescseesessesee=)} 

unit Buttons; 

{$O+,F+} 

interface 

type 


STR40 = stringl40]; 


Point = object 
x5 ¥, Cotor.s-Integer:; 
procedure Move( PtX, PtY : integer ); 
procedure Create( PtX, PtY, C : integer ); 
procedure SetColor( c : integer ); 
function GetColor : integer; 
function GetX : integer; 
function GetyY. : integer; 

end; 


ButtonType = ( Rounded, Square, ThreeD ); 
Button = object( Point ) 
Exist, State, Rotate : boolean; 
FontSize, Typeface, SizeX, SizeY : integer; 
ThisButton : ButtonType; 
BtnteKe 3" STRSU; 
procedure Draw; 
procedure Create( PtX, PtY, Width, Height, C : integer; 
Text 2: STR4O: 33 
procedure Initialize; 
procedure Destroy; 
procedure Invert; 
procedure Move( PtX, PtY : integer ); 
procedure SetColor( C : integer ); 
procedure SetState( BState : boolean ); 
procedure SetLabel( Text : STR4O ); 
procedure SetButtonType( WhatType : ButtonType ); 
procedure SetTypeSize( TxtSize : integer ); 
procedure SetTypeFace( TxtFont : integer ); 
function GetWidth : integer; 
function GetHeight : integer; 
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function GetState : boolean; 
function GetTextSize : integer; 
function GetType : ButtonType; 
function ButtonHit( Mousex, 
MouseY: integer ): boolean; 
end; 


implementation 


uses Crt, Graph; 


type 
RectOutline = arrayl1..5] of PointType; 
{SaeSeSeSSSeSseSeeesarrresseeeesesessssesessa=z } 
{ Local procedure used by Button functions } 
{sSeeSSS2SeSSe Se Sessesessseseseeesteestsessee=ss=) 


procedure SetOutline( var RectArr: RectOutline; 
‘Ct Sis key SE fF InESGS 37 


begin 
Rectarrtiti.x £2 x43 RectArrEtid.y <= yi; 
RectArri2d. x 2= 233 Reetarri22.y¥ := ye; 
REGTATTOES).% i> #2 RectArrlsd.y <= ye; 
RectArrl4] xX 12 22> RectArriéd.y¥ := ¥1> 
RectArrC5J] := RectArrlid; 
end; 
{Sees SSSSesStressesesesesseescessese=s=kres)} 
{ implementation for object type Point } 
{SsSSeSeSsststssrrteseessrressessecseseeseses)} 
procedure Point.€reate€ PtX, PtY, C :. integer ?); 
begin 
x r= PtX; 
y ss FETS 


Cotor, = ¢€; 
PytPixel<t x, y¥, Cotor 73 
end; 


procedure Point.Move( PtX, PtY : integer ); 
begin 

Createt( PtxX, Pty, Coitor 3; 
end; 


procedure Point.SetColor( c : integer ); 
begin 

Createt x, ¥; 6 22 
end; 


function. Potnt. GetCotor; 
begin 

GetColor := Color; 
end; 
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TUNETTON “Pont. GetxXs 


begin 
GetX := x; 
end; 
function Point.GetyY; 
begin 
GetY := y; 
end; 
(SS Set ees SeSerStsssseseesSssesessezces2eces= >} 
{ implementation for object type Button } 
{SSeSSrSeSseseSSeteescertsesee2e2eee22e==z===) 
procedure Button. Initialize; 
begin 


Extst. =: FALSE: 
Seti ypesSizet::10 2: 
SetTypeFace( TriplexFont ); 


end; 
procedure Button.Draw; 
const 
radius = 6; { fadtas 2} 
offset = 3; troeoftteet tor  Fttt 2 
var 


RectArr : RectOutLline; 
AlignX, AlignY, TempSize, TextLen, 
1, Btn¥e, Btnnt, Textdir:: Anteger: 
begin 
SetViewPort( x, y, x+Sizex, y#rSizey, ctlipon d; 
Grapn~seztCtotor<( color 7; 
case ThisButton of 
Square: 
begin 
Graph. Rectandte¢. 0). 9° OD, Stzeky si zey 3: 
BtnWd := Sizex - 10; 
BtnHt := SizeY - 10>; 
end; 
ThreeD: { ThreeD Outline } 
begin 
Grapn.Rectanglet-0,°:0, Sizex, -Stzrey =); 
setoutlinel RectaArr,; 1,1, Sizex-1, SizeyY-1 >); 
SetFillStyle€ CloseDotFill, color ); 
SetLineStyle(€ UserBitLn, 0, NormWidth ); 
FillPoly(€ sizeof(RectArr) div sizeof (PointType), 
RectArr 3: 
SetLineStyle€ SolidLn, 0, NormWidth ); 
Graph.Rectangle( 2*radius, 2*radius, 
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Sizex-2*radius, SizeY-2*radius ); 
Linet OU, 0; 2% tadive,. 2* radius 3; 
Line€ 0, SizeY, 2*radius,SizeY-2*radius ); 
Line( Sizex, 0, SizeX-2*radius, 2*radius 3 
Line€ Sizex, SizeY, SizeX-2*radius,SizeY-2*radius ); 
BtnWd := Sizex-4*radius; 
BtnHt := SizeY-4*radius; 
end; 
else begin 

ThisButton := Rounded; { default 

{ draw corners 
Graph.Arct Sizex+radius, radius, 0, 90, radius); 
Grapn.Arct cadius,. redius, 90, 180, radius.) > 
Graph.Arct radius, SizeY=radius, 180, 270, radius ); 
Graph.Arc( SizeX-radius, SizeY-radius, 

£°Uz° S60; radies 22 
{ draw sides 

Grepn.L inet radiue, GO, - Si2ex-radtus, Oo 23 
Graph.Line(€ radius, SizeY, SizeX-radius, SizeyY ); 
Graph.Linet 0, radius, 0, -SizeY-radies* }; 
Graph.Line€ SizeX, radius, Sizex, SizeY-radius ); 


BtnWd := SizeX-2*radius; 
BtnHt := SizeY-2*radius; 
end; 
end; € case } 
case ThisButton of ‘ P4tl Betton 
Square, 


Rounded: SetOutline( RectArr, offset, offset, 
SizexX-offset, SizeY-offset ); 
ThreeD: SetOutline( RectArr, 2*radiust1, 2*radiusti, 
SizeX-2*radius-1, SizeY=2*radius 2)? 
end; { case } 
{ show State 
1f State then SetFittistylet: SotidFitt, colar ) 
else SetFillStyle(€ WideDotFill, color ); 
SetLineStyle(€ UserBitLn, O, NormWidth ); 
FillLPoly(€ sizeof(CRectArr) div sizeof(PointType), 
RectArr d; 
SetLineStyle( Solidin, 0, NormWidth ); 
{ adjust fonts and string to fit 
TempSize := FontSize; 


Textoir := Hortzdir; { horizontal text display 
if Rotate then 
begin { vertical text display 


TextDdir = Vertdir: 
TextLen := BtnWd; { swap width and height 
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BtnwWd 

BtnHt 
end; 
SetTextStyle( TypeFace, 
TORT: Es 


BtnHt; 
TextLen; 


TextDir, 


FontSize downto 1 do 


TempSize ); 


if€ TextWidth(BtnTxt) > BtnWd ) 
then SetTextStyle( TypeFace, 


else 


TextDir, 


if€ TextHeight(BtnTxt) > BtnHt ) 


then SetTextStyle( Typeface, 
ord« Btntxtlod 23 


TextLen := 


1 


) 


Textotr,;°%4 


while€TextWidth(copy( BtnTxt,1,TextLen))>BtnWd) do 


dec( TextLen ); 
Alignk: s=.Sizex dtv.2- 
AlignY s= SizeY div:2- 
if BtatettCtTextlenJd- 2s! .* 


OutTextXY( AlignX, 


AlLignY, 


i 
3; 


then dec( TextLen ); 
if State then Graph.SetColor( GetBkColor ); 


ar 


{ €4ne: tuning. for position 3 


if State then Graph.SetColor( color ); 


SetViewPort( QO, GetMa 


end; 


0, 


procedure Button.Create( Pt 
He 


Text 


begin 
SetViewPort( O, QO, 
SetTextJustify( CenterTe 
X28 PEA 
yy £@ Ptr: 
SizeX := Width; 
SizeY := Height; 
if Sizex < 20 then Sizex 
if. S4207Y::< 20 then Sizer 


if€ SizeY > SizexX ) then 
else 

Color su Cs 

State >= FALSE; 

Exist s= TRUE; 

Btntxtese Text; 

Draw; 

end; 


procedure Button.Destroy; 
var 

OldColor 
begin 


integer; 


GetMaxX, 


EXF 


Oi ee Er 
Th pis 


Xt, 


eu 
203 
Rotate 
Rotate 


GetMaxyY, 


Width, 


GetMaxyY, 
CenterText ); 


integer; 


stRaQ 2; 


TRUE 
FALSE; 


Chinon = 23 


Clipon  %3 


copy BtnTxt,1,TextLen) 


{ add 
; 


Label } 
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if Exist then 
begin 
SetViewPort( x, y, x#+Sizex, ytSizeY, ClipOn ); 
ClearViewPort; 
Exist := FALSE; 
end; 
end; 


procedure Button.Move( PtX, PtY : integer ); 
begin 

Destroy; 

Xx s= PtX; 

y am PETS 

Draw; 
end; 


procedure Button.SetLabel( Text : STR40 ); 
begin 

BtnTxt := Text; 

Draw; 
end; 


procedure Button.SetColor( C : integer ); 
begin 

Cotor := ¢; 

Draw; 
end; 


procedure Button.SetState( BState : boolean ); 
begin 

iI1f€ State <> BState 2? then Invert; 
end; 


procedure Button.SetTypeSize( TxtSize : integer ); 
begin 

FontSize := TxtSize; 
end; 
procedure Button.SetTypeFace( TxtFont : integer ); 
begin 

TypeFace := TxtFont; 


end; 
procedure Button.SetButtonType( WhatType : ButtonType ); 
begin 
ThisButton := WhatType; 
end; 


procedure Button.Invert; 
begin 
State := not State; 
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Draw; 
end; 
function Button.GetWidth; 
begin 

GetWidth := Sizex; 
end; 
function Button.GetHeight; 
begin 

GetHeight := SizeY; 
end; 
function Button.GetState; 
begin 

GetState := State; 
end; 
function Button.GetTextSize; 
begin 

GetTextSize := FontSize; 
end; 
function Button.GetType; 
begin 

GetType := ThisButton; 
end; 
function Button.ButtonHit( MouseX, MouseY: integer ): 
var 

Result : boolean; 
begin 


Result := FALSE; 
if € MouseX >= x ) and ( MousexX <= x+SizeX ) and 
( MouseY >= y ) and ( MouseY <= y+SizeY ) then 
Result := TRUE; 
if Result then Invert; 
ButtonHit := Result; 


end; 
(* ssee====s==== end of methods ==2==2==2=2==2====2 
end. 
{SSPSSSSeseseesssssszssse2=seese==} 
{ TBoxes.PAS } 
{ creates TBoxes object unit } 
{SssSsSeeeSSSeeese2eeensseceessee)} 


unit TBoxes; 
{S$O+, F+} 
interface 


type 


boolean; 
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STR40 = stringl40]; 
BoxState = ¢ Off, Select, Invalid ); 
BoxType = ( None, Single, Double ); 
Box = object 
X> ¥p>p COLOF, Baeectetor, Sizex integer; 
Exist boolean; 
State BoxState; 
ThisBox BoxType; 
BtnTxt STR40; 


procedure 
procedure 
procedure 


procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
function 
function 
function 
function 
function 
function 
function 


Move(€ PtxX, Pty 

DrawBox; 

Create( PtX, 
Text 

Initialize; 

Destroy; 

invert; 

SetColor( C integer ); 

SetBackColor( C integer ); 

SetState( BState BoxState ); 

SetLabel( Text STR60 - 7} 

SetBoxType( WhatType BoxType ); 

GetColor integer; 

GetBackColor integer; 

GetxX integer; 

GetY integer; 

GetWidth integer; 

GetState BoxState; 

GetType BoxType; 


integer ); 


PtY, Width, C2 


STR40 ); 


es be integer; 


function BoxHit( MouseX, MouseY: integer ): boolean; 
end; 
implementation 
uses Crt; 
{sSeSeees2rerseresstessessseeceasserece==} 
{ implementation for object type Box } 
{Sse2EeSSeteteseressfereseestesessessscz=} 
procedure Box.Initialize; 
begin 
State ss OTT? 
Exist := FALSE; 
y t= 0; 
y := 0; 
Sitzex :2 0; 
Color 2 ¢@y 
BackColor := OQ; 


BtnTxt := ' 
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end; 


procedure Box.DrawBox; 
var 
Boxstr «+: stringlél; 
i, APOse, YPos : integer: 
OLGALTt#L 3 word; 
begin 
XPos := WhereXx; 
YPos := WhereY; 
OldAttr := TextAttr; 
case State of 
Off. ©. TextCotort: LightGray: >? 
select : TextColor¢ Color ); 
rAvelia: TextCotort DarkGray ?>; 
end; f{ case } 
TextBackground( BackColor ); 
case ThisBox of 
None : BoxStr 
Single : BoxStr ; 
DouGie ©: BoxStr = vale 
end; { case } 


Ce top2 Of pox *) 

GOTOKYE= BS Y 2:3 
write( BoxStr(€1J] ); 
for 1°38 2 to Sizex-1 do write BoxStris] >»: 
writet BoxStrl2J); 

(* center of box *) 
gotoxy( x). 41.23 
write( BoxStrl6] ); 
for 4. 987s ote - Si 2exk=1 do writet! '}s 
writeC BoxStrl6J] )> 
GOCOxVOsk S20 Si gex:.- ordt StntxtCol ) ) <dtve 2, y*1 25 
write€ BtnTxt ); 

C? -battom of box *) 
GOCORTU By VFS: 2-2 
writtet BoxStrt31)). 
for Fe-2 to Sizex=1. de write BoxstrlSd >, 
write ¢ BoxStri4J] ); 


TextaAtte 22 OtdAttr s 
gotoxy(: £Pos,° YPos 32> 
end; 


procedure Box.Create( Ptx, PtY, Width, C1, C2 : integer: 
Text (¢: STR4O D> 
begin 
X Fe Peas 
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vy @@ PCY 
S§izeX := Width; 
Color := C1; 
BackColor := C2; 
State OFF: 
Exist TRUE; 
BtnTxt := Text; 
while ord(BtnTxtCOJ) > SizeX-2 do 
dect BtnTtxtl0d 22 

DrawBox; 

end; 


procedure Box.Destroy,; 
var 
i, i, *Pos, YPas ¢. tAteger; 
OldAttr-: word; 
begin 
XPos := WhereXx; 
YPos := WhereY; 
if Exist then 
begin 
OLGAtTtr = TextAttr; 
TextCatert 0 2% 
for j := 0 to 2 do 


begin 
gotoxy( x, ¥¢*] 34 
for’ 1 -eF 40: SA cet do wreitet” .* 2; 
end; 
TOXtAttr se OLGATtr? 
end; 
gotoxy( XPos, YPos ); 
end; 
procedure Box.Move( PtX, PtY : integer ); 
begin 
Destroy; 
xXx := PtX; 
Y 22 PSY? 
DrawBox; 
end; 
procedure Box.SetLabel( Text : STR40 ); 
begin 


BtnTxt := Text; 
DrawBox; 
end; 


procedure Box.SetColor( C : integer ); 
begin 
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Cotor 28, 
DrawBox; 
end; 


procedure Box.SetBackColor( C 


begin 
BackColor 
DrawBox; 


C; 


integer ); 


end; 
procedure Box.SetState( BState BoxState ); 
begin 
if€ State <> BState ) then 
begin 
State := BState; 
DrawBox; 
end; 
end; 
procedure Box.SetBoxType( WhatType BoxType 
begin 
ThisBox := WhatType; 
end; 
procedure Box.Invert; 
begin 
case State of 
Of f SetState( Select ); 
Select setState( Off d;3 
Invalid begin 
Sound( 440 ); 
delay( 200 ); 
NoSound; 
end; 
end; { case } 
end; 
function Box.GetColor; 
begin 
SetColor: 3:= Cotor; 
end; 
function Box.GetBackColor; 
begin 
GetBackColor := BackColor; 
end; 
function Box.GetX; 
begin 
Getx  <28+"> 


end; 


); 
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function Box.GetyY; 
begin 

GetY := y; 
end; 


function Box.GetWidth; 
begin 

GetWidth := Sizex; 
end; 


function Box.GetState; 
begin 

GetState := State; 
end; 


function Box.GetType; 
begin 

GetType := ThisBox; 
end; 


function Box.BoxHit( MouseX, MouseY: integer ): boolean; 
var 
Result : boolean; 


begin 
MouseX := MouseX div 8 + 1; 
MouseY := MouseY div 8 # 1; 
{ for test purposes only } 
gotoxyt 25, ° 4.22 { report mouse event } 
write( 'Mouse hit position is: ',MouseX:2, 
hap Ss SASSY Fe) Fs 
gotoxy( MouseX, MouseyY ); { restore mouse position } 
{ end test } 
Result := FALSE; 
14 (€ MouseX >= x >) and € MouseX < x#Sizex 2 and 
( MouseY >= y ) and ( MouseY <= y+2 ) then 
Result := TRUE; 
if Result then Invert; 
BoxHit := Result; 


end; 
(* seeesses=== end of methods =======2====== *) 

end. 

{senses tsttssesasssssseeece=} 

! BtnTest.PAS } 

{ demonstrates Button and } 

{ TextBox object types } 

{seseeseneesssessessesezre=ss=}) 


program Button_Test; 
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uses Crt, Graph, Mouse, Buttons, TBoxes; 


var 
GMouse : GraphicMouse; 
TMouse : TextMouse; 
mButton : Position; 
GButton «: arraytlt..103 of Button: 
TBox : arreyt tT... 40) of Box; 
Exit, Status : Boolean; 
GDriver, GMode, GError, i, ji, 
SButtons, BtnCount : integer; 


procedure Create_Buttons; 
var 
1: 2: 3nteger:> 
TempStr : stringl2]; 
begin 
TOR 4238-27 46.5: do 
with GButtonlild do 
begin 
tri. 132, Tempstr i> 
Initialize; 
SetButtonType( ThreeD ); 
Create( (€1-1)*110410, €1-1)*50+10, 
100, 40, i+8, ' Test'+TempStr 
end; 
GButtonl6].SetButtonType( ThreeD ); 
GButtonl6].Initialize; 
GButtonl6].Create( 10, 260, 100, 40, White, 
end; 


procedure Create_TBox; 
var 
1 t integer: 
TempStr : stringl2]; 
begin 
Tor: J ¢= 1 te. 5: do 
with TBoxlCild do 
begin 
StreU Tid, Eenpetr 33 
Initialize; 
SetBoxType( Double ); 
Create( €i-1)*1541, (€1-1)*541, 


15, 446,47 -" Fest*+Tempstr 2; 


end; 
with TBoxl6] do 
begin 
SetBoxType( Single ); 


)Z 


ie aa ee ae 
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Initialize; 
Create 1, 21,. 18, White, OF Rarer 
end; 
with TBoxl7J] do 
begin 
SetBoxType( Double ); 
Inttiatize; 
Createt 61, 1, 153 White, GO, ‘“SEnvettd’ >); 
SetState( Invalid ); 
end; 
end; 
begin 
GDriver := Detect; 
InitGraph(€ GDriver, GMode, '\TP\BGI' ); 


{ } { if you have a low res mouse } 
{ SetGraphMode( 1 ); _ } { and a high res video, then } 
{ } { you may need to include this } 


GError := GraphResult; 
if GError <> grOk then 
begin 
writeln('Graphics error: ',GraphErrorMsg(GError)); 
writeln('program aborted...'); 
nel eCCT?T 
end; 
ClearDevice; 
Create_Buttons; 
GMouse.Reset( Status, BtnCount ); 
Exit t= FALSE; 
for 7 s*. 1 to T0 do 
begin 
GButtonlil]d.Initialize; 
TBoxCil.Initialize; 
end; 
if Status then 
begin 
GMouse.Initialize; 
repeat 
GMouse.QueryBtnDn( ButtonL, mButton ); 
if mButton.opCount > O then 
begin 
GMouse.Show( FALSE ); 
for 41) ¢=-1. to 6 do 
if GButtonlil].State then GButtonlild.Invert; 
Tor 45. 50:1. to. 6. do 
if GButtonlCild.ButtonHit( mButton.XPos, 
mButton.YPos ) then 
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delay( 100 ); 
delay( 100 ); 
delay( 100 ); 


TRUE; 


begin 
GMouse.Show( TRUE ); 
Sound: 1%220: )+ 
sound( i*t1Q@ 2) 
if 1: =.6 then Exit := 
end; 
GMouse.Show( TRUE ); 


end; 
RECT Ext ty 


CloseGraph; 


NoSound; 


NoSound; 


{ close graphics and restore } 
{ text mouse operation 


{ set up for text button operation } 


TMouse.Initialize; 
Exit t= FALSE; 
Cirsecr: 
gotoxyt:-26, 
write('This 
Create_TBox; 
repeat 


e423 


TMouse.QueryBtnDn( ButtonL, 


mButton ); 


if mButton.opCount > O then 


end; 
end. 


begin 
TMouse.Show( FALSE ); 
TOR ee DP be le deo 
if€ TBoxlild.State = Select ) then 
TBoxCil.Invert; 
Tors . 88 Seo Bao 
if TBoxClild.BoxHit( mButton.XPos, 
mButton.YPos ) 
begin 
TMouse.Show( TRUE ); 
souna¢ 1%42é€0 3% detey¢ 100 2: 
delay( 100 ); 
sound(€ 1*110 DJ; detay( 100 )> 
Tt To @ then: Este ec TRUE? 
end; 
TMouse.Show( TRUE ); 
end; 


UCT Sette: 
delay(500); 


1s a Text Button test routine'): 


then 


NoSound; 


NoSound; 


} 


Chapter 31 


Extending Objects 


The basic principles of object-oriented programming shown thus far are applicable 
to all object types. In simple forms, you have seen how an object can be created and 
then extended to form a new object type. Also in previous examples, some degree 
of data abstraction has been used. 

In this chapter, the theory of data abstraction will be brought up again, along 
with the theory and practice of extending objects and the potential problems and 
opportunities inherent in doing so. 


Object Data Abstraction 


While the theory and principles of data abstraction were explained earlier (See the 
Encapsulation section in Chapter 28), this topic will recur periodically. Now that 
you have seen how an object can be referenced indirectly though methods, rather 
than calling its values directly, and how an object can be prevented from relying on 
global variables, I will again emphasize the importance of providing complete 
object methods. 

In the example objects presented in Chapters 29 and 30, a complete series of 
methods were provided for all conceivable accesses required—even though the 
demo programs themselves did not require all of them. Furthermore, while the 
units created contain quite a few unreferenced object methods (since the Turbo 
Pascal linker does not include any methods that are not actually used by the 
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program), there is no penalty—in terms of the compiled program size or perfor- 
mance of the program—for being thorough. 

There is a big advantage in designing the object with complete access methods 
because the object itself can later be redesigned internally—as long as the original 
access methods are retained. This can be done without requiring any applications 
using the object to be rewritten, they only need to be recompiled in order to include 
the revised object. 

Later, if it becomes necessary to add a new access method or to expand the 
performance of the object, since only hindsight is 20/20, this can be done with 
complete freedom as long as the object’s original methods are still supported. 

The degree of freedom afforded by providing complete access methods is 
virtually unlimited. Since none of the object’s internal variables are accessed 
directly by name, all of them can be renamed or restructured as necessary, their 
internal handling rewritten entirely or any manner of alteration performed as long 
as it does not affect the manner in which the object responds to the calling 
application. 

Remember, this freedom of revision is not totally unlimited. There is one 
caution to keep in mind: any descendants of an altered object will be affected by the 
revisions. Of course, the degree to which revisions will require updating descendant 
objects depends on the parent and child objects and the nature of the revisions. In 
general, renaming internal variables will require revision of child objects, but 
rewriting the procedures used internally should not require revisions of child 
procedures as long as the same inputs are used and the same objective result is 
achieved. 

For the same reason, the example objects previously created used internal 
method calls wherever possible (for example, the implementation of an object 
method may call another method belonging to the same object rather than using 
duplicate code). As a secondary benefit, this also produces economy both in the 
source code and compiled program and is good practice in any type of program- 
ming—not merely object-oriented programming. 

Other aspects of methods provisions will be discussed later in this chapter. 


Extending Objects 


Objects are extended by defining a new object type as a descendant of an existing 
object, a technique shown in Chapter 28 and again in Chapter 30, but extending 
objects can take many different forms. 
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In standard Pascal, a few procedures such as Write and WriteLn can accept a 
variable number of parameters and varying parameter types, for example: 
Write( "A string message' ); 

UreteLint 'The €ursér 18 ats. ts Ree, ts *, Y¥ir!2 22 

Unfortunately, however, Pascal does not allow programmers to create equally 
flexible procedures of their own and even the graphics analogues of the Write and 
WriteLn procedures, OutText and OutTextXY, lack the originals’ convenience and 
will accept only a single string argument for output. 

Object-oriented programming does restore a portion of this desired flexibility 
through inheritance: each descendant object type inherits the methods and data 
fields of its ancestor type, but can add whatever new methods and data fields are 
necessary for a specific application. It does so without having to totally recreate the 
parent object. 

Also, the parent object’s methods may be overwritten—replaced with new 
methods applicable to the specific requirements of the new object. 


Static Method Inheritance and Overrides 


Axiomatically, each descendant object inherits all of the methods belonging to the 
parent object, but this does not mean that the descendant object is bound to perform 
exactly like the parent. Instead, any inherited method which is inappropriate to the 
new object’s purpose can either be ignored or overwritten—the latter being the 
more appropriate choice. 

As an example, in Chapter 30, the Button object was created as a descendant of 
the Point object type and it then inherited the Move, Create, SetColor, GetColor, 
GetX and GetY methods defined for Point. 

But, for the Button object, the Move, Create and SetColor methods were 
overwritten by defining new methods, using the same names but not always with 
the same calling parameters. 

For the Point object, the three methods in question were defined as: 


procedure Move( PtX, PtY : integer ); 
procedure Create( PtX, PtY, C : integer ); 
procedure SetColor( C : integer ); 


And for the Button object, the same three method names were defined as: 


procedure Move( PtX, PtY : integer ); 
procedure Create( PtX, PtY, 
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Width, Height, C : integer; 
Text. ¢ STRAT 22 
procedure SetColor( C : integer ); 


Now, the changes in the Create method are obvious: three new parameters, two 
integers and one string, which did not appear in the Point method have been added, 
thus requiring a new method for handling. 

What about the Move and SetColor methods? These do not appear to have 
changed. However, if you examine their implementations, the differences become 
more apparent: 
procedure Point.Move; 
begin 

Createt FPtx, PtY, Color 2; 
end; 


procedure Button.Move; 


begin 
Erase; 
X SS REARS 
¥ se ers 
Draw; 
end; 


procedure Point.SetColor( C : integer ); 
begin 

ChSHCGt A, tT, CdS 
end; 


procedure Button.SetColor( C : integer ); 
begin 

Color fe: <:: 

Draw; 
end; 

In actual fact, the differences are misleading. As created, the Point object type, 
which has not been used for real applications except to serve as a convenient parent 
for other object types, is relatively unsophisticated. As it stands, the Point.Move 
method simply creates a new point on the screen but does nothing to erase the 
earlier screen image—a programming flaw provided to point out one type of 
possible error. 

At the same time, the Button object type has been provided with the mecha- 
nisms necessary (in the Move method), to erase an existing button before recreating 
a new image at a new position. In turn, the Button.SetColor method uses the 
provisions originally made for the Move method. 
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Now, suppose that the Point object was given the same sophistication as the 
Button object: the ability to erase an existing point in response to a Move. If this 
were done, the two pairs of procedures could look like this: 


procedure Point.MoveC Ptx, PtY =: integer J; 


begin 
Erase; 
X $3 POR: 
Y £=  Pti: 
Draw; 
end; 


procedure Button.Move( PtX, PtY : integer ); 


begin 
Erase; 
xXx $= PtK2 
y t% PTT? 
Draw; 
end; 


procedure Point.SetColor( Color : integer ); 
begin 

Lotor €=. C3 

Draw; 
end; 
procedure Button.SetColor( Color : integer ); 
begin 

Color t= C2 

Draw; 
end; 


The two paired methods are now identical. 


Is there any further reason for redefining the Move and SetColor methods for 
the Button object? 


Static Method Inheritance 


Obviously, the previous question is intended as a trap. If the answer No sprang to 
mind, consider yourself snared because it is vitally important for the Move and 
SetColor methods to be redefined. The reasons are not always obvious. 

The object methods appearing here are called static methods as opposed to virtual 
methods. The conflicts discussed in this section are specific to static methods. Virtual 
methods, which provide a second solution to these problems, will be discussed 
later. 
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Using static methods, the flaw in not redefining the Move method for the Button 
object is simply that the Point.Move method calls the Point.Erase and Point.Draw 
methods, not the Button.Erase and Button.Draw methods (see also the Compiler 
Operations section). Since the Point.Erase and Point. Draw methods have very little 
to do except to erase and draw a single screen pixel, they have virtually no relevance 
to the Button object. The same is true of the two SetColor methods that call two 
separate, and far from identical, Draw methods. 

On the other hand, the GetColor, GetX and GetY methods defined for the Point 
object do not need to be redefined for the Button object and can be used as is with 
perfect accuracy. Thus, which methods must be redefined for child objects depends 
entirely on the parent and child objects and the tasks that must be implemented by 
the methods. 


Dot Referencing 


Dot referencing was introduced in Chapter 30, in the Button object implementation, 
when it was used to explicitly call the Graph.SetColor procedure, avoiding a 
conflict with the Button.SetColor procedure. This is not, however, the only reason 
for using dot referencing. 

In general, any inherited method can be explicitly referenced using the form, 
Ancestor.Method. For example, assume that the Point object has been rewritten as 
previously suggested and now includes a method titled SetLoc which is defined 
as: 


procegure Settioc( Ptx, PCY -3- tnteger >> 


begin 
x = PtX; 
y = PtY: 
end; 


With the SetLoc method provided, the Point.Move method can be simplified: 


procedure Point.Move( PtX, PtY : integer ); 
begin 
Erase; 
SetLoct: FEX, PCY 2s 
Draw; 
end; 


Since the SetLoc method belongs to the Point object, no dot reference is required 
here. In like fashion, the Button.Move method can be rewritten to also call the parent 
method SetLoc: 
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procedure Button.Move( PtX, PtY : integer ); 
begin 

Erase; 

Point.SetLoct “Per; Fro 2 

Draw; 
end; 

Now, in this particular case, the dot reference is redundant because the Button 
object has not redefined the inherited SetLoc method; thus, the call automatically 
goes to the Point object’s method. 

Suppose, however, that the Button object has its own version of SetLoc: 


procedure Button.SetLoc( PtX, PtY : integer ); 
begin 
Button specific handling provisions 
Point. 8etboct: Ptx, PTY. 23 
Button specific handling provisions 
end; 


In this case, the Point.SetLoc dot reference would be absolutely necessary both 
here, to prevent a recursive loop, and in the Button.Move method (unless, of course, 
Button.Move was intended to call Button.SetLoc). In conclusion, dot referencing 
may be used for three purposes: 


1. To resolve conflicts between object methods and external routines that 
have the same name. 

2. To allow child methods to explicitly call ancestor methods that have 
been overwritten in the child object. 

3. Toallowa child method to call an explicit ancestor method where sev- 
eral generations of objects have redefined the method two or more 
times. 


Global Variables 


Global variables should not be referenced or required by objects! Having stated 
this, I will proceed to qualify the statement in several fashions. 

First, all variables declared within an object definition are global to the object 
and its methods. Therefore, while these are global variables, this is true in a more 
limited sense than usual, but within the object the variables may be treated in the 
same fashion as variables declared for a procedure are global to the procedure’s 
subprocedures. (The variables declared within the object’s methods are valid only 
within the method.) 
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The second qualification is broader because there can be cases where a true 
global variable is simply the best solution to a program’s needs. For example, an 
editor utility might be written as an object using dynamic memory allocation to 
store text data, such that the data is available to the calling application with the 
object returning pointers to the data’s location in memory. 

For simplicity, a variety of memory pointers might be global both to the object 
and to the application; if so, the declaration of the pointer variables should be made 
within the object unit—not by the calling application (I am assuming that an object 
of this type would be compiled as a referenced unit and not included within the 
main program’s source code). 

Third, predefined constants and flag values (or even flag variables) are more 
convenient if declared globally, however, these should always be declared within 
the object unit, not by the calling application. For those of you who wish to quibble 
that global constants are not global variables: you are correct, but remember that 
the computer is a worse quibbler than thee. 

Last, the original statement stands as rephrased: no object should reference nor 
require externally declared global variables. Attempting to do so will limit the 
portability (from application to application of the object), will prevent the object 
(and its descendants) from being compiled as program units and, finally, is bad 
programming practice. 


Inheriting Data Fields 


Data fields, as well as methods, are inherited by child objects, but unlike inherited 
methods, inherited data fields cannot be overwritten or redefined. If necessary, 
however, inherited data fields can be ignored or used for purposes not originally 
intended. You cannot define a new data field with the same identifier as an inherited 
data field or change the structure of an inherited data field. 


Compiler Operations for Static Methods 


The inheritance problems described above are a product of the Pascal com- 
piler/linker operations specific to static methods. Virtual methods are handled in 
a different fashion, but before the solution is explained, it helps to understand the 
problem. 

The source of the problem is the means by which the compiler resolves method 
calls (or procedure or function calls in conventional Pascal). When the compiler 
encounters the Point.Move method, the Erase, SetLoc and Draw methods already 
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have addresses within code segment. Later, when another method or the main 
program makes a call to the Move method: 


Move PtX, PtY 2; 


becomes the equivalent of: 


Erase; { Point.Erase address } 

SetLoc( PtXk,. PtY 2; { Point.SetLoc address } 

Draw; { Point.Draw address } 
This is also the reason that forward declarations are used — to provide 


addresses to procedures and functions for the compiler’s use before the actual code 
is encountered. (Note: this also reduces the need for the multiple passes required 
by some compiler languages.) 

Now, assume that the Erase and Draw methods are also reimplemented for the 
Button object, but the Move method has not been reimplemented. When a Button 
object calls the Move method, the result is still a series of calls to the Point methods, 
not the Button methods. 

When the compiler encounters the reference Button.Move, it looks first in the 
Button method definitions, but if no Move has been defined for the Button method, 
the compiler moves up to the immediate ancestor of the current object type, 
continuing to regress until the method referenced is found. Of course, if no such 
method is encountered, the compiler terminates, issuing an error message that the 
method named is not defined. 

Even though the Button object has its own Erase and SetLoc methods, the Move 
method called is Point. Move and—with static methods—the reference addresses 
of the Erase and Draw methods refer only to the Point implementations, not the 
Button implementations. 

When the Button.Move method is implemented (see Figure 31-1), then the 
compiled result correctly becomes: 


Erase; { Button.Erase address } 
Setioe € . Ptx, PRY. 73 { Point.SetLoc address } 
Draw; { Button.Draw address’7 } 


The SetLoc method, which simply assigns the calling parameters to the x- and 
y-axis location variables, is not redefined for the Button object. 

Remember: when the inherited methods are static methods, the method called 
is the method precisely as it was defined and compiled for the ancestor type. If the 
ancestor type calls other methods, the addresses of the subsequent methods called 
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will be those of the ancestor type—even when the descendant object has defined 
methods overriding the ancestor methods. 


Figure 31-1: Static-Linked Object Method Calls 


with Button do 
Move(x,y) 


with Point do 
Move(x,y) 







Point.SetLoc ia 


Point.Move 
Erase 
SetLoc(x,y) 
Draw 





“In otherwords, to bind a method to a message (that is, a function call), the 
compiler must look at the type of the object involved and select the appropriate 
method for the message.”—HyperGuide to Turbo Pascal 5.5 by Brian Flamig. 

HyperGuide to Turbo Pascal 5.5 is a public-domain utility available on Compu- 
Serve in the BPROGA forum. 


Static vs. Virtual Methods 

While static methods work, they do not provide the optimum flexibility that we 
desire for object-oriented programming, however, they still should be considered 
the basic tools for OOP. Note that there are more versatile tools available and virtual 
methods offer an alternative in which the structure and programming demands are 
not so rigid. 

The main difference between a static and a virtual method lies in the point at 
which the methods are linked or bound. Static methods, as shown, are subject to a 
process called early binding with their links determined at the time a program (or 
unit) is compiled; this is shown in Figure 31-1. 
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Alternatively, late binding—used with virtual methods—does not create any 
fixed links between methods and calling procedures. Instead, at compile time, a 
binding mechanism is installed which will link the method and the calling process 
at the time the call is actually executed. 

How virtual methods are created and how the mechanisms for virtual methods 
work will be shown, beginning in Chapter 32. 


Summary 
This chapter has reviewed the basic elements of object-oriented programming 
using static object methods and, at the same time, suggested a number of revisions 
for the Point and Button object types originally created in Chapter 30. 

In Chapter 32, virtual methods will be the topic and the Point and Button objects 
will modified once again, this time with previously static methods becoming virtual 
methods. The suggested revisions appear in the following listings. 


fsssseeisssstecsetce ce sacks } 
{ BUTTON2.PAS } 
{ creates BUTTON2.TPU  } 
{ thlustrating static. 2 
{ method inheritance } 
{ssseseteeesenee2eeeee=r2e2e= } 
unit Button2; 
interface 
type 
STR40 = stringl40); 
Point = object 
x, Yy, Color : integer; 
procedure Move(€ PtxX, PtY : integer ); 
procedure Draw; { new } 


procedure Create t Pts, PLY, .¢ tointeger 2); 
procedure SetcColort ¢ Integer... 
procedure SetlLoc( PtX, PtY 2: tnteger >); { new } 
procedure Erase; { new } 
function GetColor + integer; 
function GetX : integer; 
function GetyY +: tnteger; 
end; 


ButtonType = (€ Rounded, Square, ThreeD ); 
Button = object Point ) 
Exist, State, Rotate : boolean; 
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FontSize, Typeface, SizexX, StzeY': integer; 
Style : ButtonType; 
Btnix<e 2“ SIR40: 
procedure Draw; 
procedure Create PtxX, PtyY, 
Wigth,; Heignat, CC. : integer: 
TEXT 2° STRAD Ds 
procedure Initialize; 
procedure Erase; 
procedure Invert; 
procedure Move( PtX, PtY : integer ); 
procedure SetColor( C : integer ); 
procedure SetState( BState : boolean ); 
procedure SetLabel( Text : STR40 ); 
procedure SetButtonType( WhatType : ButtonType ); 
procedure SetTypeSize( TxtSize : integer ); 
procedure SetTypeFace( TxtFont : integer ); 
function GetWidth : integer; 
function GetHeight : integer; 
function GetState : boolean; 
function GetTextSize : integer; 
function GetType : ButtonType; 
function ButtonHit( MousexXx, 
MouseY: integer ): boolean; 
end; 


implementation 


uses Crt, Graph; 


type : 
RectOutlLine = arrayl1..5] of PointType; 
{(SsSSeSss St Sr SesSSSes SSS seseecsreesssessesessss} 
{ local procedure used by Button functions } 
(SS SeereseSseseeteeeseteersetseteste2rceaeseee22eee2} 
procedure SetOutline; { no changes } 
{Sesa ere eeeeesteeccsssesssesesseeseeea see =} 
{ implementation for object type Point } 
(Sssesesetesetrestsessesersesrezeseseeseze-) 
procedure Point.SetLoc; { new } 
begin 
xX £2. PTA F 
y 12-7272 


end; 


procedure Point.Draw; 
begin 


PutPixet*’ &> ¥) Sobor 2; 
end; 
procedure Point.Create; 
begin 
Setioct Ptk,s Fer 32> 
Color = C3 
Draw; 
end; 
procedure Point.Erase; 
var 
Temp =: thteger; 
begin 
Temp := Color; 
Color °= GetBkCocor; 
Draw; 
Color := Temp; 
end; 
procedure Point.Move; 
begin 
Erase; 
Setioct Ptx, PY 2; 
Draw; 
end; 
procedure Point.SetColor; 
begin 
Cotor 328° C3 
Draw; 
end; 
function Point.GetColor; 
function Point.GetX; 
function Point.GetY; 
{SSSSSSee2S2 2S 22SSSSSSeesrseeseeree=s=sezee=5 
{ implementation for object type Button 
{SssSSSeS2S S22 Se SSS2S2SSSSE2SSSSsessesczezrze= 


procedure Button.Initialize; 


procedure Button.Draw; 
procedure Button.Create; 
begin 


SetViewPort( 0, 0, GetMaxX, 
SetTextJustify( CenterText, 
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GetMaxY, ClipOn ); 
CenterText ); 


{ new } 


{ revised } 


no 
no 
no 


no 
no 


{ new 


revised 


revised 


changes 
changes 
changes 


changes 
changes 
revised 


} 


Y 


Y 
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Settoct Ptr, PtyY 23 
¢- Width <-20 then Sizex :=, 20 
else SizeX := Width; 
1f Height <.20: then SizgeyY := 20 
else SizeY := Height; 
if€ SizeY > SizeX ) then Rotate := TRUE 
else Rotate := FALSE; 
Color = C; 
State = FALSE; 
Exist = TRUE; 
BtnTxt = Text; 
Draw; 
end; 
procedure Button.Erase; {10 
procedure Button.Move; { 
begin 
Erase; 
Seticoet Ptx, PtY 23 
Draw; 
end; 
procedure Button.SetLabel; + Ao 
procedure Button.SetColor; t+ > no 
procedure Button.SetState; { no 
procedure Button.SetTypeSize; + 6 
procedure Button.SetTypeFace; t no 
procedure Button.SetButtonType; { no 
procedure Button.Invert; { no 
function Button.GetWidth; { no 
function Button.GetHeight; { no 
function Button.GetState; { no 
function Button.GetTextSize; { no 
function Button.GetType; { no 
function Button.ButtonHit; { no 
(*® sssssezzz==z= end of methods =t=za=z=z=222==2==2==22 * ) 


end. 


changes 
revised 


changes 
changes 
changes 
changes 
changes 
changes 
changes 
changes 
changes 
changes 
changes 
changes 
changes 


The BtnTest demo program requires one change to use the revised unit, BUT- 


TON2.TPU, thus: 


program Button_T 


uses Crt, Graph, 


{ssscecesasnesss52=)} 
Co BINTESTESL PAS } 
{seeeeenzecsessszeaa=} 
est <2; 
Mouse, Button2, TBoxes; 


{ no further changes 


a ee ee ee we ee eee 


required } 


Chapter 32 


Virtual Object Methods 


While static methods are addressed and resolved at compile time and use fixed 
references, virtual methods are dynamically referenced. At compile time, virtual 
methods are compiled, but references calling the virtual methods or references 
within one virtual method calling another virtual method, are not resolved (i.e., the 
references are not replaced by link addresses at this time). 

For example, assume that the Point and Button objects previously demon- 
strated are recreated with the Erase and Draw methods changed from static to 
virtual methods. In this case, instead of addresses replacing the method references 
in Move, virtual references are made which will be resolved later — at run time 
instead of at compile time. 

If method addresses are not resolved at compile time, how can they be resolved 
at run time? 


The Virtual Method Table 


Instead of replacing method calls with method addresses, the compiler creates a 
new element for each virtual object type: the Virtual Method Table or VMT which 
becomes part of the data segment of each object type definition. 

Each VMT contains a variety of information including the object type’s size and, 
for each of the virtual methods belonging to the object type, a pointer to the virtual 
method’s implementation code. These pointers to the implementation codes for the 
methods are used at run time to resolve the method calls, linking each to the 
appropriate implementation. 


623 
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Figure 32-1 shows a partial diagram for the Point and Button object methods 
and the Virtual Method Tables created for each, compare this figure with the static 
implementation links shown in Figure 31-1. 


Figure 32-1: Methods Using VMT References 


















Button.Erase [V] 


Iv) 






[Vv] 
[vl 


[s] 

Point. Move [Ss] 
Erase— 

“SetLoc(e.y)—> 


Point.Erase. 


Point.Draw Button.Draw 








Point.SetLoc . 
















In the static version shown previously, even though both versions were defined 
identically, the Move method was still redefined for the Button object so that 
Button’s version would call Button.Erase and Button.Draw instead of Point.Erase 
and Point.Draw. 

Instead, for the virtual methods version, notice that while Point.Move is still 
static, no Button.Move method is defined. The Point. Move method has unresolved 
references to the virtual Erase and Draw methods. The SetLoc method, which also 
remains static and is not redeclared by the Button object, is still referenced directly 
by its implementation address. 

To satisfy the unresolved references, Point’s VMT contains implementation 
addresses for Point’s Draw and Erase methods, while Button’s VMT inherits Point’s 
method addresses, but adds its own Draw and Erase addresses. In this fashion at 
run time (see Figures 32-2 and 32-3), a Button instance calling Point’s Move method 
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still uses the Button.Erase and Button.Draw methods while a Point instance calling 
Move uses Point.Erase and Point.Draw methods. 

This is precisely what virtual methods are for! By using virtual methods, when 
a new descendant of either Point or Button is created, the Move method does not 
need to be redefined, not even when the new object has its own versions of Erase 
or Draw because they will be used automatically. 

Suppose that a descendant object, titled ScrollBar, defines a new version of 
SetLoc? So far, the SetLoc method has been statically linked. What happens now? 
Two possibilities occur here, depending on whether the new ScrollBar.SetLoc 
method is created as a static or virtual method, but in either case the solution is the 
same. The Move method will need to be redefined (as ScrollBar.Move for the 
descendant object type) before the ScrollBar.SetLoc method will be used. This is 
because the Point.Move method is still statically linked to Point.SetLoc. 

Second, it is preferable, when ScrollBar redefines SetLoc, to make SetLoc a 
virtual method so that future revisions and/or descendants will not need to further 
redefine the Move method which, itself, is already a virtual method. Keep this in 
mind, it will be important later. 

Assuming that only these two redefinitions are required (SetLoc redefined as 
a virtual method; Move redefined, but still static; and the Erase and Draw methods 
remain unchanged), an instance of ScrollBar calling the Move method appears in 
Figure 32-4. 

This time, the Point.Move method is not referenced at all. Instead, the Scroll- 
Bar.Move method is linked by virtual reference to the Button.Erase, ScrollBar.Set- 
Loc and Button.Draw methods. Any descendant objects of ScrollBar will not need 
to redefine the Move method, even if they redefine the Erase, SetLoc or Draw 
methods. What about the Move method itself? Should it have been a virtual method 
from the start? Or should ScrollBar.Move be declared as a virtual method? 

So far, nothing has been done that actually requires either of the Move methods 
to be virtual and, even if both were virtual methods, their effective execution would 
not be affected in any way. Instead, it is the fact that the methods called by the two 
Move methods are virtual; that accomplishes the principal task. 

On the other hand, if the Point.SetLoc method had originally been defined as 
a virtual rather than a static method, only the original Point.Move method would 
be needed and no redefinition of the ScrollBar.Move method would be required. So 
why not declare all methods virtual and simply be done with it? 
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Figure 32-2; A Point Instance Calling the Move Method 
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Figure 32-3; A Button Instance Calling the Move Method 
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It could be done, but with two small flaws. First, each virtual method requires 
an entry in the object’s Virtual Methods Table—which requires a small, but real 
amount of space. Second, execution of the program would be slightly slower with 
each instance of an object requiring a small slice of time for the instance’s construc- 
tor to consult the VMT and link the virtual method calls to the appropriate 
addresses. 
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Figure 5-4: A ScrollBar Instance Calling the Move Method 
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Static vs. Virtual 


As a general rule, static methods are used to optimize for speed and memory 
efficiency, while virtual methods provide extensibility. 

As a rule of thumb, if any method is likely to be redefined by a descendant 
object and the redefined method should be accessible to the ancestor, then the 
method should be created as virtual rather than static. 

But, if an object has any virtual methods, a VMT is created for that object type 
in the data segment and every instance of the object will possess a link to the VMT. 
Every call to a virtual method references the VMT, while static methods are called 
directly by the address. 

While the VMT is efficient, the static method calls remain slightly faster than 
virtual calls and, if no VMT is required or created, then a small savings in code size 
is realized. 
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In the end, one of the points of object-oriented programming is extensibility, 
allowing the extension of existing code without recompiling the source code; this 
is achieved, in part, by using virtual methods. Don’t forget the possibility that later 
users of your object types will probably think of ways of employing the object type 
which were not anticipated when the object type was created. This, in the final 
analysis, is what extensibility is all about! 


Static Methods Redefined as Virtual 


Despite the preceding cautions, static methods are not necessarily dead-ends and, 
instead of all methods being initially and unnecessarily declared as virtual, any 
descendant object type can redeclare a static method as a virtual method. 

If you refer back to Figures 32-1, 32-2 and 32-3, you should notice that both 
Point.Erase and Button.Erase, and Point.Draw and Button.Draw are indicated as 
virtual methods (indicated in the diagrams by the shorthand notation [V]). Once 
any method is defined as a virtual method, all descendant redefinitions of the 
method must also be virtual. 

The drawback, of course, in redeclaring a static method as a virtual method, is 
that complete information about the original declaration is required in order to 
redefine the complete method, while an initial virtual declaration permits extensi- 
bility without revealing the original method’s source. Also remember, static to 
virtual redefinition is a one-way street and a method which was previously virtual, 
cannot be redefined as static! 


Creating Virtual Methods 


Having talked about the theoretical how and why of virtual methods, it’s time to 
move on to the practical aspects, beginning with how a virtual method is declared. 

Virtual methods are declared simply by appending the reserved word virtual 
to the method declaration. Beginning with the Point object declaration in the 
Buttons unit, the changes appear as follows: 


Point = object 
X> -¥, SOter.4- integer, 


conetructoer intt;: { new } 
praeceqcure Createt Ptx, Pty; ¢C- © inteder 2: 

procedure Move( PtX, PtY : integer ); 

procedure Draw; virtual; { revised } 


procedure SetColor: ¢ 3: integer: '2> 
procedure SetLoc( Ptx, PtY : integer ); virtual; 
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{ revised } 
procedure Erase; virtual; { revised } 
function GetColor : integer; 
function Getx : tnteger: 
function GetY : tnteger: 

end; 


In addition to the keyword virtual being appended to the SetLoc, Draw and 
Erase methods, you should also notice that a new method, titled Init, has been 
declared using the reserved word constructor. A constructor is a special type of 
procedure provided to handle some of the initial setup work required for virtual 
methods. They will be discussed in a moment. For the present, simply remember 
that the object’s constructor method must be called before any virtual methods are 
used. Otherwise, if a virtual method is called before the object constructor, a system 
hang-up will occur. 

Note also that the compiler does not normally test the order in which methods 
are called and cannot tell you if an object’s constructor method is not called 
correctly—see the Range Checking and Virtual Method Calls section. 

For the Button object, the Draw and Erase methods are redefined, but are again 
defined as virtual—not static—methods. Remember, once a method has been 
defined as virtual, all descendant methods must also be defined as virtual. The 
remaining virtual method defined in the Point object, SetLoc, is not redefined in the 
Button object. 

The Initialize method defined in previous versions has now become the con- 
structor method, Init. The name change has been made for compatibility with the 
identifier suggested in the Turbo Pascal OOP Guide, though the tasks executed by 
the Button.Init method have not been changed: 


Button = object( Point ) 
Exist, State, Rotate : boolean; 
FontSize, Typeface,  Stzex, SizeyY =: integer; 
ThisButton : ButtonType; 
BtnTxt : STR4@; 
constructor Init; { revised } 
procedure Draw; virtual; { revised } 
procedure Create( PtX, PtY, 
Width, Height, €-3:-tnteger ; 
Text ¢ STR&¢C 2 
procedure Erase; virtual; { revised } 
{ no further declaration changes } 
end; 
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Aside from these three changes in the declarations, the remainder of the 
methods are declared exactly as they appeared in the previous versions of the 
Button unit. But there are a couple of additional other revisions. First, the Point.Init 
method is new and has to be defined in the implementation section of the Button 
unit: 
constructor Point. inte; 
begin 
end; 

Please note: the preceding code is not an error. The fact that the Point.Init 
method implementation does not contain any instruction is perfectly correct 
because, in this case, nothing is required except the constructor call itself. 

Alternatively, the Point.Create method could have become the constructor, but 
this particular version is used to illustrate the importance of the constructor call, 
irrespective of any secondary tasks accomplished by the constructor method. 


Constructor Methods 


The constructor method is vital to objects using virtual methods because it is the 
constructor call that establishes the link between an object instance and the object 
type’s Virtual Method Table. Without this link, any call to a virtual method simply 
leads to some never-never-land where it can not be resolved, and the result is a 
hang up that can only be corrected by resetting the computer. 

Each object type using virtual methods has a single VMT, but the individual 
instances of an object type do not contain copies of the VMT itself. The only way 
that an object instance can access the VMT is through the link created by the 
constructor call. 

Obviously, the constructor method cannot be a virtual method; because the 
constructor implementation could not be called by the object until after the con- 
structor had supplied the link to the VMT. The link identifies the address of the 
constructor implementation which is only done in response to the constructor call. 
While recursion is permitted, this type of circular bootstrap recursion is not. The 
constructor method therefore, is always static. 

Each individual instance of a method—whether the method instance is static 
or dynamic (see Chapter 34)—must be initialized by its own constructor call. Thus, 
one instance of a method cannot be initialized and then subsequently assigned to 
other instances because only the first, initialized method instance will contain a 
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correct link to the VMT and the remaining instances—if virtual methods are 
called—will produce a system hang-up. 

The constructor method also has wide applicability and it is not necessary for 
every method to have a constructor method. For example, the Button object in the 
Button3 demo does not require redefinition of a constructor method, but can simply 
inherit the Point.Init constructor which will correctly initialize each Button 
instance’s link to the Button VMT, not to the Point VMT. 

At the same time, since the constructor method is always static, descendant 
objects are free to overwrite inherited constructor methods without the constraints 
imposed by virtual methods (i.e.,a descendant’s constructor method is not required 
to match the calling format of the ancestor’s constructor). 


Range Checking and Virtual Method Calls 


Turbo Pascal has provided a ‘safety net’ feature in the form of the $R compiler 
directive. In the active state ($R+), before compiling any virtual method call, the 
compiler tests the initialization state of the instance placing the call, issuing a range 
check run-time error if the instance calling the virtual method has not been 
initialized (by first calling the constructor method). 

After a program has been debugged, execution can be speeded by setting the 
$R toggle to inactive ($R-), but uninitialized virtual method calls will no longer be 
trapped and an error of this type will probably cause a system hang up. 

Obviously, when virtual methods are used, each object definition must contain 
at least one constructor method and the $R toggle can be used to test, indirectly, for 
the omission of a constructor call. 

There is, however, a second possible error that cannot be trapped quite so easily 
— the presence of a redundant, duplicate constructor declaration within an object’s 
definition or both an inherited constructor call and a newly declared constructor 
call. This second error is not fatal and will not prevent a program from executing 
correctly, but it does add a small amount of unnecessary overhead to the unit or the 
EXE program. (A brief test using the Button3 unit, declaring the Button3.Create 
method a second constructor, added 32 bytes to the .TPU unit and 48 bytes to the 
.EXE program, but otherwise executed correctly.) 


Summary 


This chapter has provided an introduction to virtual methods, discussing the theory 
behind virtual methods, the reasons for using virtual methods instead of static 
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methods, and some of the trade-offs involved. The constructor method type has 
also been introduced and explained, together with the $R toggle used to test object 
instance initialization. Finally, the Button unit has appeared ina third revision using 
virtual methods (listings showing all necessary changes for the Button3 unit and 


BtnTest3.PAS follow). 


Next, the ScrollBar object, cited as an example in the current chapter, will finally 
be created as a descendant (however unlikely) of the Button type. This will be 
accomplished using the Button4.TPU unit (a slight modification of the Button3 
unit), rather than adding to the source code—to show how object extensibility 


actually works. 


{sSesSeSeestetesacsaseeeeee=-%2=2}) 
{ Button3.PAS } 
{ introducing virtual methods } 
{SSeeseeseeseeeresnesseeeresazzzz==} 


unit Buttons; 


interface 
type 


STR40 = stringl40]; 


Point = object 

Kp: Vw (COVOr integer; 
constructor Intty 

procedure Create( PtxX, 
procedure Move( PtX, PtY 
procedure Draw; virtual; 
procedure SetColor( c : 
procedure SetLoc( PtX, 


dee te ertuies & 


integer ); 
Pty 


procedure 

function 

function 

function 
end; 


Erase; virtual; 
GetColor integer; 
GetX integer; 
GetY integer; 


ButtonType = ( Rounded, 
Button = object( Point ) 
Exist, State, Rotate boolean; 
FontSize, Typeface, Sizex, Stzey 
ThisButton ButtonType; 
BtnTxt STR40; 
constructor: Init: 
procedure Draw; virtual; 


Square, 


integer ); 


imtedqer. 2: 
integer ); 


ThreeD ); 


integer; 


{ new } 


{ revised } 


virtual; 


Y 


{ revised 
{ revised } 


{ revised } 
{ revised } 
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procedure Create( PtX, PtY, Width, Height, C : integer; 
TERE So SERA 

procedure Erase; virtual; { revised } 

procedure Invert; 

procedure Move( PtX, PtY : integer ); 

procedure SetColor(€ C.: integer ); 

procedure SetState( BState : boolean ); 

procedure SetLabel( Text : STR40 ); 

procedure SetButtonType( WhatType : ButtonType ); 

procedure SetTypeSize( TxtSize : integer ); 

procedure SetTypeFace( TxtFont : integer ); 

function GetWidth : integer; 

function GetHeight : integer; 

function GetState : boolean; 

function GetTextSize : integer; 

function GetType : ButtonType; 

function ButtonHit(€ MouseX, MouseY: integer ): boolean; 
end; 


implementation 


uses Crt, Graph; 


type 
RectOutline = arrayl1..5] of PointType; 
(SSSSSSsSSSSSSSR SSeS sree aseseeeeeezerzezee===} 
{ local procedure used by Button functions } 
(SSS SeSSeeeSSSSeS2eSSs See 5e22e2e2e22=e2==} 
procedure SetOutline( s v2 { no change } 
(SSESSeSSSSS2SS SSS ese 2225S 2222 22ee222) 
{ implementation for object type Point } 
({SSSSSSSSSSSSSSSe2S22e22e8 e522 2225222} 
constructor Point.Init: { new 
begin { no instructions required 
end; ‘fer th i¢6 method... 


no change 
no change 
no change 
no change 
no change 
no change 
no change 
no change 
no change 


procedure Point.SetLoc; 
procedure Point.Draw; 
procedure Point.Create; 
procedure Point.Erase; 
procedure Point.Move; 
procedure Point.SetColor; 
function Point.GetColor; 
Tinction Poitnt,Getx>; 
fTunetion Potnt.GetyY; 


AAA AA KAA 
Me YYYeeeeey Yew 
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constructor Button.Init; 


begin 
Exist 


SetTypeFace( TriplexFont 


end; 


procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 
procedure 


function 
function 
function 
function 
function 
function 


end. 


:= FALSE; 
SetTypeSize( 10 ); 


Button 


Button. 
Button. 
Button. 
Button.Move; 
Button. 
Button. 
Button. 
Button. 
Button. 
Button. 
Button. 
Button. 
.-GetHeight; 
Button. 
Button. 
Button. 
Button. 


Draw; 
Create; 
Erase; 


SetLabel; 
SetColor; 
SetState; 
SetTypeSize; 
SetTypeFace,; 
SetButtonType; 
Invert; 
GetWidth; 


GetState; 
GetTextSize; 
GetType; 
ButtonHit; 


AAA AAAAAAAAAAAAA A 


end of methods 


program Button_Test_3; 


uses Crt, 


var 


Graph, 


{sese2sseeee2e2ee22) 
{ BINTESTS. FAS: 2 
{seseessteeeeee22e2) 
Mouse, Button3, TBoxes; 


{ revised 


no 
no 
no 
no 
no 
no 
no 
no 
no 
no 
no 
no 
no 
no 
no 
no 
no 


change 
change 
change 
change 
change 
change 
change 
change 
change 
change 
change 
change 
change 
change 
change 
change 
change 


a ee 


{ no changes } 


procedure Init_Buttons; 


var 


1 2 -trteger: 


TempStr 


begin 
for4 


stringt223 


va 4 to 5 do 
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with GButtonlCild do 
begin 
estrt ts2_ FeRosatr 2; 
EWE? 
SetButtonType( ThreeD ); 
Create( €1-1)*110+10, (€i1-1)*50+10, 


{ revised } 


100.405. 146," Feet*+Tempstr ?; 


end; 
GButtonl6].Init; 
GButtonl6].SetButtonType( ThreeD ); 
GButtonl6].Create( 10, 260, 100, 40, 
| Snite, *Qurtt D3 
end; 


procedure Init_TBox; 
begin 


end; 


begin 
GDriver := Detect; 
InitGraph( GDriver, GMode, ‘\TP\BGI" ); 
GError := GraphResult; 
if GError grOk then 
begin 
writeln('Graphics error: ‘, 
GraphErrorMsg(GError)); 
writeln(€'program aborted...'); 
haltcd); 
end; 
ClearDevice; 
Init_Buttons; 
GMouse.Reset( Status, BtnCount ); 
Exit ¢= FALSE; 
for i := 1 to 10 do 
begin 
GButtonlild.Init; 
TBOXCTIV,IALtsatize; 
end; 
; { no 
end. 


{ revised } 


{ no changes } 


{ revised } 


further changes } 
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Chapter 33 


Scrollbars and Object Extensibility 


In this chapter, object extensibility with be the principal topic. To demonstrate 
extensibility, the ScrollBar object will be developed as a descendant of the Button 
object type. 

Previously, examples have been created by building on existing source code or 
by modifying an existing object type. But correctly demonstrating extensibility, 
even when the ancestor source code is readily available, requires creating a descen- 
dant object type from an already compiled ancestor. Before developing the ScrollBar 
object, a few modifications will be made to the Button object unit to improve its 
own extensibility. 

First, however, a review of the what and why of extensibility is in order. 


Object Extensibility 


Object extensibility is one of the principal advantages of object-oriented program- 
ming. Using extensibility, toolbox units can be created and distributed to users in 
linkable .TPU form as modifiable sources for use in creating their own applications. 

For distribution purposes, the source code of an object-oriented unit can remain 
the property of the developer, while the distributed unit does not require release of 
any more documentation than the interface portion of the unit. Additional docu- 
mentation, however, is suggested for clarity and the user’s convenience. 

Because the source code itself is not distributed, programmers are able to 
maintain a proprietary interest in their software development and, at the same time, 
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can develop new versions of distributed packages without sacrificing compatibility 
with previous versions. 

Extensibility is simply a method of distributing programming toolboxes because 
toolbox units can conveniently be used, modified and extended by their original 
developers without the necessity of recompiling the original source codes. 

Extensibility is derived from two elements: object inheritance and late binding. 
Object inheritance allows a descendant object to possess everything the ancestor 
object owned. Late binding permits new and old object methods to meld together 
so that extensions of existing objects and methods are created without imposing 
performance penalties beyond a brief reference to the Virtual Method Table. 


Programming for Extensibility 


The Button and Point objects have been created and subsequently modified to 
demonstrate different aspects of object-oriented programming. At the same time, 
any considerations that were not immediately relevant to the topic of discussion 
were ignored and a few programming elements were written in the simplest 
possible fashion to avoid digressive explanations. Some topics however, can only 
be differed so long. The time has come, as the Walrus said, to speak of many things. 

Programming for extensibility requires two parts advance planning and one 
part hindsight and revision. While it is both impossible and impractical for a 
programmer to anticipate every descendant object type that will later be created 
from a unit, there are a few guidelines which can be applied. 

Please realize: these are not hard, fast rules—defining absolute rules would be 
even harder than anticipating all possible descendant object types, but these are 
suggestions which will reduce the amount of hindsight and revision required. 


Tool Declarations 


Any tools that will be required to implement a unit should, if at all practical, be 
declared within the unit’s interface section and not depend on the application 
program for declaration or inclusion. 

For example, in the previous versions of the Button unit, the Mouse unit did 
not appear in the uses declaration. Instead, the three demo programs called on the 
Mouse unit and defined the graphic mouse instance which was used to operate the 
object Button instances. In this final revision of the Buttons unit (titled BUT- 
TON4.PAS), however, the Mouse unit is declared within the unit: 
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interface 
uses Crt, Graph, Mouse; 


An instance of the GraphicMouse object, GMouse—which was previously left 
to the application to provide—is also declared as a variable in the unit interface : 


var 
GMouse : GraphicMouse; 


In this fashion, the GMouse instance is available both to the object methods in 
the unit and to any application using the unit, but it is also available to any 
descendant objects. Reasons for this will be demonstrated soon. 


Procedure and Function Availability 


Any procedures or functions used by an ancestor object will probably be needed 
by a descendant object. Obvious, right? 

The obvious is the easily overlooked and in Buttons, Button2 and Button3, there 
is one very useful procedure that is not available to any descendants created by 
extensibility, which means that the extensibility of the unit is limited. 

The procedure in question is the SetOutline procedure which, beginning with 
the original Buttons unit in Chapter 30, appears in the implementation section of 
the unit. 

Because the SetOutline method was not intended for general use (i.e., was not 
intended to be called directly by any application using the unit) SetOutline was not 
created as a method. Still, the SetOutline procedure was available to the Buttons 
methods and would also be available to any other object methods within the same 
unit, so what’s wrong? 

What’s wrong is that the SetOutline method is not—as created—available to 
any descendant object defined outside of the Buttons unit. Extensibility, therefore, 
suffers. To repair this omission, two changes are required. First, the RectOutline 
type definition is moved from the implementation section of the unit to the interface 
section: 
type 


STR40 = stringl40]; 
RectOutlLine = arrayl1..5] of PointType; 


This change makes the RectOutline type definition valid not just for the current 
unit methods, but also to any applications using the unit and, more importantly, to 
any descendant object types created outside the current unit. 
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But, the type definition is only one aspect and the procedure itself also needs 
to be available to descendant objects. As previously defined, it is not. 

Instead, to make the SetOutline procedure inheritable, it has to become a 
method and, since it hardly belongs to the Point object type, it is now added to the 
Button object definition as: 


Button = object( Point ) 


procedure SetOutline( var RectArr: RectOutline; 
Ro VG REY Yak Anteger. 23 


end; 


The body of the SetOutline procedure is not changed except to modify its 
header, making it a Button method, and moving it—purely for organizational 
reasons—in with the rest of the Button methods: 


procedure Button.SetOutline; 
begin 


RectArroetd kx 2:25 ¥12 RectArrhiasyY 28 ys 

ROctarfrig).x 28° 43 RECtArri¢gia.y t2 y2> 

RectArrl3J.x := x2; RECTAL USG Ty re ye: 

RectArriad.%- t=. %25 RectArrl4J.y := yl; 
R 


RectArrtss t= RectArrtti; 


end; 


The remaining Point and Button method definitions are unchanged and the 
Button4 unit is otherwise the same as Button3 from Chapter 32. The revisions 
discussed here appear in the listings at the end of this chapter. 


The ScrollBar Object 


The ScrollBar object type is probably a familiar feature. It appears in a variety of 
graphics-based applications ranging from drawing and design utilities to Windows 
and OS/2 Presentation Manager applications. Even if you haven’t yet encountered 
scrollbar controls, their operation should be self-explanatory. 

In this case, the ScrollBar objects were chosen for two purposes: to demonstrate 
extensibility, as well as to create a second useful graphics control feature. 

Despite the fact that Buttons and ScrollBars have relatively little in common, 
the ScrollBar object is defined as a descendant of the Button object type, inheriting 
the Button data and method elements, but also defining new methods and elements 
peculiar to the ScrollBar object type. 
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Two instances of the ScrollBar object type appear in Figure 33-1. 


Figure 33-1: ScrollBar Control Objects 


For demo purposes, the vertical and horizontal scrollbars are controlled by 
the mouse, in turn controlling the position of the Exit button which teminates 
the program. 





The scrollbars can be operated in three fashions: by clicking on either endpad, 
by dragging the thumbpad or by clicking anywhere else on the scrollbar 
(which moves the thumbpad to the indicated location). 


Ms ee eee eee Vv 


Creating the ScrollBar Object 


The primary difference between previous examples and the ScrollBar object and 
the ScrlBar unit is that these are created as an extension of the Button4 unit; 
therefore, ScrlBar.PAS begins with a uses statement: 


unit... SertBar; 
INTERFACE 
uses Button4, Graph; 


The Button4 unit is referenced because the current object will be defined as a 
descendant of the Button object type. While the Graph unit was referenced by the 
Button4 unit, this earlier reference does not carry forward to the current unit and, 
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therefore, must be repeated here to validate the variable declaration to the View- 
PortType—which is defined in the Graph unit—as well as later calls to procedures 
in this unit. 

Two data types are defined, beginning with HitType which is used by the 
ScrollHit method both as an internal flag and to report scrollbar selection events to 
the calling application. The second data type, Direction, is used to select a horizontal 
or vertical scrollbar: 
type 


HitType 


= ( NONE, RIGHT, UP, HBAR, VBAR, LEFT, DOWN ); 
Direction = 


C Vertical, Horizontal ): 


The ScrollBar object begins by declaring itself a descendant of the Button object 
type from the Button4 unit, and then adds four new variables: 


ScrollBar = object( Button ) 
ScrollMove : Direction; 
LineColor, SPos, Step : integer; 
VRef : ViewPortType; 

The ScrollMove variable, of course, is the orientation of the ScrollBar. Since two 
color specifications are needed for ScrollBar object, the LineColor variable supple- 
ments the original Color variable inherited from the Button object type. Of the 
remaining new variables, SPos is used to track the thumbpad (slider pad) position 
for the scrollbar and Step is a local variable controlling the movement increment of 
the thumbpad. 

Since the ScrollBar object is likely to be used with a graphics window, the VRef 
variable is used to retrieve and store the current viewport (window) settings. 

Previously, in the Button3 unit, the method’s Init constructor did little or 
nothing (Point.Init was defined as an empty procedure) aside from providing the 
constructor call to create a link to the object type’s VMT: 


constructor Inittt, Pex, Pty, Stee, C1....62 3 integers: 
Orientation :' O0frecttean >: 


This time, for the ScrollBar object, the Init method assumes the functions which, 
for the Button and Point objects, were assigned to the Create method so that 
initialization and creation of the object instance are now accomplished by a single 
method call. In most cases, this will be the preferred form for an Init method and 
you may wish to rewrite the original Button object type to follow it. 
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The SetLoc method will be redefined for the ScrollBar object type and, at this 
time, is made a virtual method in recognition of the possibility (and probability) 
that future descendants may require further variations of the SetLoc method: 


procedure Setloet PEA, FtY + integer 2: virtuat-? 
procedure Draw; virtual; 


The Draw method has already been declared as a virtual method, but the 
ScrollBar object requires very different drawing instructions from the Button 
method and therefore, is also redefined. 

The SetThumbPad and EraseThumbPad methods are designed primarily for 
use by the Draw and ScrollHit methods and do not require any parameters aside 
from the object instance’s own variables. Likewise, the RestoreViewPort method is 
used to restore the graphics window settings after a viewport change is used to 
create a graphics screen element. While none of these three methods is intended for 
direct use by an application, any method may be called directly if desired: 


procedure SetThumbPad; 
procedure EraseThumbPad; 
procedure RestoreViewPort; 
function GetPosition: integer; 
function Getdirection: Direction; 
Tunctien SerettHit<t? Hittiype; 
end; 
Of the remaining methods, the GetPosition method reports the thumbpad 


(slider pad) position relative to the scrollbar—not the screen—while the Get- 
Direction method simply reports the scrollbar orientation as horizontal or vertical. 

The final ScrollBar method, ScrollHit, is the workhorse method of the ScrollBar 
object. As you can readily discern from the method declaration, the ScrollHit 
method does not require any parameters, but does return an argument reporting 
the scrollbar hit type. This indicates either no scrollbar hit (NONE), horizontal or 
vertical endpad hits (RIGHT, UP, LEFT or DOWN), or a mouse hit somewhere 
within the body of the scrollbar (HBAR or VBAR). The HitType returned by the 
ScrollHit method can be used by the calling application to decide what action 
should be taken in response to the event. 

This is not by any means all that ScrollHit accomplishes (which is one good 
example of why units should have more documentation than simply the interface 
section of the object code). 
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Unlike the Button object that required the calling application to pass mouse 
coordinate parameters to determine a button hit event, the ScrollHit method is able 
to retrieve mouse coordinates directly—a much simpler procedure. 

But this is also why the Mouse unit is added to the Button4 uses declaration 
and the GMouse variable is declared within the Button4 unit instead of relying on 
the calling application to define a mouse handle or to provide mouse button event 
information. These two revisions could have been made in the Scr|Bar unit instead 
of the Button4 unit—since neither is currently required by the Button or Point 
objects. But, after seeing how the mouse is called by the ScrollBar.ScrollHit method, 
you may well prefer to revise the ButtonHit method for similar handling, in which 
case, the revisions will be necessary in the ButtonX unit and would be redundant 
in the ScrlBar unit. 

After retrieving the mouse coordinates, the ScrollHit method determines the 
mouse pointer position relative to the scrollbar coordinates and decides on the 
HitType, as well as adjusting the thumbpad position within the scrollbar. In 
addition to retrieving mouse coordinates, the ScrollHit method turns off (hides) the 
mouse pointer before updating the scrollbar image and then restores the mouse 
pointer image when done. All of this is smoother and faster than relying on the 
calling application to prevent graphics conflicts with the mouse pointer. 


The ScrollBar Constructor 


The ScrollBar.Init method, which is also ScrollBar’s constructor, is called with 
parameters setting the scrollbar’s position, outline and fill colors and orientation 
(horizontal or vertical) and begins by setting minimums, constants and initial 
values for the object instance. 

Since the ScrollBar is designed and intended for use with application windows, 
the Init method begins by retrieving the current viewport settings. The viewport 
settings are used for two purposes: first, to restore the original window settings 
after a graphics drawing routine has changed viewport settings and; second, 
because the window origin offset is necessary to translate mouse positions from 
absolute screen coordinates to window (viewport) coordinates: 


constructer. ScrollBar.Init; 
begin 
GetViewSettings( VRef ); 
if Size < 100 then Size := 100; 
ScrollMove := Orientation; 
Step := Size div 100; 
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The Init method also sets a minimum width (or height if vertical) of 100 pixels 
and establishes the Step increment by dividing the overall size by 100. Both values, 
of course are optional—see the section titled Omissions. 

Of course, the SizeX and SizeY parameters —which were inherited from the 
Button object type—have to be set according to the ScrollMove orientation: 


case ScrollMove of 


Vertical : begin SizeX := 20; 
SizeyY s:= Size: “ene: 
Horizontet .: begin... St26X 3] Size; 
Sizey 3:= 203 end; 


end; {case} 

SPos := 273 

An arbitrary thickness of 20 pixels is also set and the initial position of the 
thumbpad is established at the left or top of the scrollbar. Last, the PtX and Pty 
parameters are passed on to the SetLoc method, the two color parameters are 
assigned, the Exist variable is turned on and the Draw method is called to create 
the scrollbar image: 


SettLoc( Ptx, PY 93 
Linestotor -= Ct? 


Cotor +2: C22 
Exist <= TRUE; 
Draw; 

end; 


The Restore ViewPort Method 


The RestoreViewPort method is a convenience provided to restore the original 
graphic window settings. It uses the VRef (ViewPortType) variable which was set 
when the object instance was initialized: 


procedure ScrollBar.RestoreViewPort; 
begin 
with VRef do 
Set vVieePror kee Ri, Fie ORS Ye, BTS: 23 
end; 


The SetLoc Method 


The SetLoc method originally defined in the Point object is redefined here, making 
the coordinates relative and, at the same time, adjusting the SizeX and SizeY 
parameters to ensure that the object does not exceed the window limits: 
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procedure ScrollBar.SetLoc; 


begin 
with VRef do 
begin 
Ae RT + RP eky 
Yo ge o¥t. ©. Ptt, 
white” Stzex + X &: X22). do: dect Sizex:. 2; 
whitet..gt+z2eY + ¥ = VY2°) toe: deet) Sizer: 2: 
end; 
end; 
The Draw Method 


The Draw method was defined in the Button4 unit as a virtual method, but is 
redefined here because the ScrollBar object has different graphic drawing require- 
ments: 


procedure ScrollBar.Draw; 
var 
RectArr = RectOutline; 
OLatotor 3: word; 
begin 
OldColor := Graph.GetColor; 
Graph.SetColor( LineColor ); 
SetViewPort( x, y, x+Sizex, ytSizeY, ClipOn ); 


The Draw method begins by saving the current color before setting a new 
drawing color and a new viewport to accommodate the scrollbar image. The next 
step is to draw the scrollbar outline as a solid bar: 


Setouttine: RectaArr, Ty. 1, Sizertet, Sizey=1. 
SQtRs14Stytet SoltaFittl, coteor.d: 
SetLineStyle(€ SolidLn, O, NormWidth ); 
FillLPoly(€ sizeofCRectArr) div 
sizeofCPointType), RectArr ); 


This step could also be accomplished using the Bar procedure from the Graph- 
ics unit, but since the tools are already defined from the Button methods, the 
established format is repeated here. 

Two arrow images are now drawn at each end of the solid bar using the thick 
line style: 

Graph.SetColor( GetBkColor ); 


SetLineStyle(€ SolidLn, O, ThickWidth ); 
case ScrollMove of 
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Vertical: 

begin 
Eine 400 Bye ame sy 
Line At 65: tbe 2 2) 
bined 9s &y Ty 16°23 
Linet 107 SizeY~-4, 4; Si zer=t2°-2 
Lineé 10, SizeY¥-4,.16; SizeY¥-12 > 
Linet- 40,. $$ zev%=—65 10, Sizery=-16 2? 

end; 

Horizontal: 

begin 
Lanett 65.405 te, "°& 33 
Ete We 8G Tey: 16. 2s 
Ct Aet ees 105° 16696) 2 
tinetStzex-4, 10, Sizex=12, 42 
Ltnet Sizex-4, 10; Sizex~-12,- 16/73 
Line( SizexX-4,: 10, Sizex=-16, 10 

end; 

end; {case} 
SetLineStyle(€ SolidLn, 0, NormWidth ); 


we Se Be 


we Ne Ne 


At this point, the scrollbar image is a solid bar with an arrow at each end. The 
next step is to erase the center of the bar in order to leave two solid ends (the 
endpads) and also an outline along the length of the scrollbar: 


Graph.SetColor( LineColor ); 
SetFillStyle(€ SolidFill, Graph.GetBkColor ); 
case ScrollMove of 
Vertical: SetOutline( RectArr, 1, 21, 
Si 2exX-—1,, Sizey-21 2; 
Horizontal: SetOutline( RectArr, 21, 1, 
SizexX-21, SizeY-1 ); 
end; {case} 
FIiLLPoly( sizeof(RectArr) div 
sizeof(PointType), RectArr ); 


Finally, the Draw method restores the original color setting. It does so before 
calling the SetThumbPad method which creates the thumbpad image: 


Graph.SetColor( OldColor ); 
SetThumbPad; 
end; 
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The SetThumbPad Method 


The Set!humbPad method draws a dot-patterned square within the scrollbar 
outline, beginning by saving the current color and then setting the viewport to the 
scrollbar outline: 


procedure ScrollBar.SetThumbPad; 


var 
RectArr >: RectOutline; 
OlLacolor : word; 

begin 


OldColor := Graph.GetColor; 
Graph.SetColor( GetBkColor ); 
SetViewPort( x, y, x#Sizex, y#Sizeyv, Clipon )2 


The thumbpad image is created using the predefined CloseDotFill pattern and 
the current instance’s Color, while the LineColor is used for the solid outline around 
the thumbpad: 


Graph.SetColor( LineColor ); 
SCtFIiLiStytet ClosedDotRilt, Color >): 
case ScrollMove of 
Vertical: SetOutline( RectArr, 2, SPos, 
Sy SPOSe??: 2s 
Horizontal: SetOutline( RectArr, SPos, 2, 
SPos*#19, 18 )> 
end; {case} 
FilLPoly(€ sizeof(RectArr) div 
sizeof(€PointType), RectArr ); 


Finally, the original color setting and viewport are restored: 


Graph.SetColor( OldColor ); 
RestoreViewPort; 
end; 


The EraseThumbPad Method 


The EraseThumbPad method is essentially the same as the SetThumbPad method 
except that the background color and the SolidFill pattern are used, again ending 
by restoring the original color and viewport settings: 


procedure ScrollBar.EraseThumbPad; 
var 
RectArr > RectOutline; 
OldColor : word; 
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begin 
OldColor := Graph.GetColor; 
Graph.SetColor( GetBkColor ); 
SetViewPort( x, y, xtSizex, ytSizeY, ClipOn ); 
SetFillStyle( SolidFill, Graph.GetBkColor ); 
case ScrollMove of 
Vertical: SetOutline( RectArr, 2, SPos, 
18, SPos+20 2; 
Horizontal: SetOutline( RectArr, SPos, 2, 
SPost+19, 19 ); 
end; {case} 
FilLLPoly( sizeof(RectArr) div 
sizeof(PointType), RectArr ); 
Graph.SetColor( OldColor ); 
RestoreViewPort; 
end; 


The ScrollHit Method 


The ScrollHit method is the heart of the scrollbar operations and it begins by setting 
a default value (NONE) for the local variable Result: 


function ScrollBar.Scrotllhit; 
var 
Result : HitType; 
BtnStatus, XPos, YPos : integer; 
begin 
Result := NONE; 
GMouse.GetPosition( BtnStatus, XPos, YPos ); 


Instead of calling the ScrollHit method with parameters for the mouse pointer 
location, Scroll Hit calls the GMouse.GetPosition method directly to retrieve its own 
mouse button status and coordinate information. For simplicity, the button status 
information is not presently tested by the ScrollHit method, but could be used for 
confirmation of button down or button release status if desired. 

Depending on whether the ScrollMove variable indicates the current instance 
is horizontal or vertical, the mouse coordinates are tested against the scrollbar 
position variables (with corrections from window coordinates to absolute screen 
coordinates) to decide if a scrollbar hit has occurred and if so, what type of hit has 
occurred: 

case ScrollMove of 


Vertical: 
if( XPos >= x ) and (¢ XPos <= x+20 ) and 
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( YPos >= y ) then 
if YPos <= y+20 

then Result := UP else 
if YPos <= y+tSizeY-21 

then Result := VBAR else 
if YPos <= y+SizeyY 

then Result := DOWN; 

Horizontal: 
1tC. VPos F= 2 yy and: ¢  ¥Ros<«<*:¥#20 ) end 

( XPos >= x ) then 
if XPos <= x+20. 

then Result := LEFT else 
if XPos <= x+Sizex-21 

then Result := HBAR else 
if XPos <= x+SizexX 

then Result := RIGHT; 

end; {case} 


Now, if you are a confirmed Pascal programmer, the preceding if..then..else.. 
structure may look like something out of the dark ages—like it should be inscribed 
on vellum with floral elaborations—and your first thought is probably why not 
replace this mess with a case statement like this: 

Horizontal: 


if€ YPos >= y ) and (€ YPos <= y+20 ) then 
case XPos of 


x.-Xt20 : Result = LEFT; 
Xx#21..x+SizeX-21 : Result := HBAR; 
x+SizeX-20..x+Sizex : Resutt = RIGHT; 


end; {case} 
end; {case} 


Obviously the same thought occurred to me, however, there is one problem: 
the compiler is not able to evaluate the expressions used in the case statement. A 
small matter perhaps, but in this case, the if..then..else.. structure works and the 
case structure does not. 

The current ScrollBar method tests for a hit anywhere along the scrollbar image. 
If the hit is not on either of the endpads or the thumbpad, the scroll position will 
jump abruptly to the selected location. In some applications, you may prefer to 
guard against such rapid movements by restricting hits to the endpads and to the 
thumbpad. In order to implement this provision, an alternate form appears in the 
listings at the end of this chapter. 
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At this point, ScrollHit has identified where the mouse hit occurred, but hasn’t 
yet taken any action asa result. If Result is not NONE, then a response is appropriate: 


if Result <> NONE then 


begin 
GMouse.Show( FALSE ); 
EraseThumbPad; 


The response begins by turning off the mouse pointer and then erasing the 
current thumbpad. 

Next, depending on where the mouse hit occurred, the thumbpad position 
(SPos) is adjusted either bythe Step increment if one of the endpads was hit or, if 
not, to move the thumbpad to the mouse pointer position: 


case Result of 
LEFT, UP*+ gect 'S$Pos,. Step. .2> 
REAR? Bros t= KPos =< € x * 10 2 
VBAR: SPos := YPos - ¢€ y + 10 );3 
RIGHT... DOWN: tne’ SPos, Step 22 
end; {case} 


The resulting position is then checked, first against the scrollbar origin, then 
against the limit (size) of the scrollbar: 


1TX SPos <. 29° 2? then SPos := ‘243 
case Result of 
LEFT, HBAR, RIGHT: 
if€ SPos > Sizex-41 ) then 
SPos := $1zeX-41; 
UP, VBAR, DOWN: 
if€ SPos > SizeY-41 ) then 
SPos = S$izeY=-41>3 
end; {case} 


Last, the Set!humbPad method is called to restore the thumbpad image, the 


mouse pointer is turned on again and, Result is reported back to the calling 
application: 


SetThumbPad; 
GMouse.Show( TRUE ); 
end; 
ScrollHit := Result; 
end; 
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The ScriTest Demo 


The ScrITest demo program creates the screen shown in Figure 33-1, allowing you 
to experiment directly with the scrollbar operations. The position of the included 
“Exit” button is controlled directly by the two scrollbars and will maneuver around 
the screen in response to the scroll operations selected. 

Aside from these few comments, the ScrlTest program is essentially self-explan- 
atory. Have fun. 


Omissions 


There are several methods, that have not been provided by the ScrollBar object 
definition—omissions intended to keep the present demonstration relatively sim- 
ple—but which could be quite useful in actual applications. 

First, while the ScrollHit method calls the GMouse.Position method directly to 
retrieve the mouse button status and position information, the mouse button status 
is not tested or used. However, the ScrollHit method could be rewritten so that, 
once a scrollbar hit was established, it would loop continuously, performing its own 
tests and moving the thumbpad until the mouse button was released or the mouse 
cursor moved away from the scrollbar. Now—and this is a loaded question—would 
this implementation be good or bad? If so, why or why not? I’ll come back to this 
later. 

Second, what about a provision to change the mouse pointer from an arrow 
image to a glove pointer, either when the mouse pointer is over the scrollbar image 
or when the mouse button is pressed? 

Third, how about a method provision to allow an application to directly control 
the thumbpad (slider pad) position along the scrollbar? This wouldn’t be wanted 
for every application, but could be quite useful in many circumstances. 

Fourth, should provisions be made to change the scrollbar colors without 
having to recreate the scrollbar from scratch? 

Fifth, what about provisions to change the thickness of the scrollbar and the 
size of the endpads and thumbpads. 

Sixth, what other provisions could be made to improve the efficiency and/or 
the performance of the scrollbar? 

Here are a half-dozen questions to mull over and, after you have experimented 
with the ScrlTest program, you may have a half-dozen of your own. The first 
question concerned making the ScrollHit method essentially self-contained so that 
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once called, it would conduct its own operations until the mouse button was 
released or the mouse pointer moved away from the scrollbar. What’s wrong with 
this? 

If you only want the scrollbars to control the scrollbar images, nothing. What 
about the external application which is calling the scrollbar to control its own 
operations? In the demo program, the scrollbars are used to move the Exit button 
image around the screen, but if the scrollbar instance does not exit until it can return 
a NONE result, how would the button image ever be updated? 

If updating was done every time a ScrollHit method returned, regardless of the 
reported result, how would this look? Jerky? Large, sudden movements only? What 
about flicker when the mouse button was pressed somewhere other than over a 
scrollbar? 

In some circumstances, a delayed response might be desired, but this would be 
relatively rare and could be implemented within the calling application without 
restricting the object methods to such a limited and unwieldy operation. 

So, before making a method too efficient, consider how it affects the application 
using the object. 


Summary 


In this chapter, a new object type, the ScrollBar object, has been created using the 
extensibility feature of object-oriented programming. At the same time, several 
elements have been shown in the ScrollBar methods which could well be incorpo- 
rated in the earlier Button and /or Point methods— including making them directly 
responsible for querying mouse position and button information and making each 
window-sensitive in terms of position. 

For example, the Button object defined previously does not test the coordinate 
provided on either a Create or Move operation to see if these are valid for the screen 
size or for the window size—while the ScrollBar object does possess at least a 
rudimentary self-test capability to decide if it can be correctly displayed. Objects 
can be much more powerful than conventional procedures and functions, but to 
balance this power, they must also exercise some care to ensure proper operation. 

If you are beginning to tire of the graphics objects used for demonstrations so 
far, Chapter 34 will begin with text-based objects to demonstrate a new aspect of 
object-oriented programming: dynamic objects. 
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{seseessessrrsssrssssssesesc=esssz} 
{ Button4.PAS } 
{ demonstrating extensibility  } 
Se 


unit Button4; 
interface 


uses Crt, Graph, Mouse; 


type 
STR40 = stringl40]; 
RectOutline = arrayl1..51] of PoitntType; 


Point = object { no changes 


ButtonType = ( Rounded, Square, ThreeD ); 
Button = object( Point ) 
Exist, State, Rotate : boolean; 
FontSize, TypeFace, SizexX, SizeY : integer; 
ThisButton : ButtonType; 
BtnT st + STRS&U? 
constructor Init; 
procedure SetOutline( { new method 
var RectArr: RectOutline; 
Co Rey! Ve eS Te eer aS 
procedure Draw; virtual; 
{ no other changes 
end; 


var 
GMouse : GraphicMouse; { new variable 


implementation 


{ SetOutline procedure moved to become Button method } 


(SSeS SsrssSssteeereseresasseceseeesasseszsz} 
{ no changes in Point implementation } 
{Sessa SESS Sees Seesrseeresesessstesesessecss } 
{SSescr reese eSeeckaerssSessseeecaesaeeseesescza==} 
{ implementation for object type Button } 
{SsereSeesee sss eeetersstzeseessssteressese=)} 


constructor Button.Init; 
begin 
EX7St (=. FALSE; 
SetTypeSize( 10 ); 
SetTypeFace( TriplexFont ); 
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procedure Button.SetOutline; 


begin 
RectArr(l1] 
RectArrl2] 
RectArrt3 J 
RectArrl4] 


KES Mie ROGCTArPLiduy +2 -¥T> 

ce ta et RectArri2id.y t= ye2; 

<a CRORES ReCctArrtsid.y 2:3 -y2:3 

<x £2) KES RectArrl4l.y := y1; 
R 


RectArrl5] :s= RectArrC{ti; 
end; 
{ no further changes to Button methods } 
(* sz======= end of methods ==2222222e= *) 
end. 
(SSsseseesessesessessesse=sz==} 
{ ScrlBar.PASs } 
{ scrollbar objects } 
(SSesSsSeeeeee2e2ee5ee2222===} 
unit ScrlBar; 
interface 
uses Button4; 
type 
HitType = (€ NONE, RIGHT, UP, HBAR, VBAR, LEFT, DOWN ); 
Direction = (€ Verticaet,. Horizontal. 7: 
ScrollBar = object( Button ) 
ScrollMove DirecttTon: 
LineCotor, SPfos, Step integer; 
VRef ViewPortType; 
COnetTPuctar Initc. PtX, Ptv, S12eG-b.. £2 integer; 


procedure 
procedure 
procedure 
procedure 
procedure 
function 

function 


Direction ?; 
integer ); virtual; 


Orientation 
SetLoct PtXk, Pry 
RestoreViewPort; 
Draw; virtual; 
SetThumbPad; 
EraseThumbPad; 
GetPosition: integer; 
GetDirection: Direction 
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function ScrollHit: HitType; 
end; 


implementation 


uses Crt, Graph; 


constructor ScrollBar.Init; 
begin 
GetViewSettings( VRef ); 
it Stze < 100 then Size s:=.1003 
ScrollMove := Orientation; 
SPos := 21; 
Step := Size div 100; 
case ScrollMove of 


Vertical : begin Sizex := 20; 
Sizey. 1:8 $120; end; 
Horizontal : begin Sizex := Size; 
SizeYy:2 20; end; 


end; {case} 
SetkoctG:: PEx,  PtyY -); 
Color pms CZ; 
Linetotor <2: Ct; 
Exist ce TRUE? 
Draw; 

end; 


procedure ScrollBar.SetLoc; 


begin 
X sB KUTSPUX; 
Yor Y¥T#Pty: 


whi-le€ 4%: 842eX% > X22: do deetCcStzex > 
white ¥ 4 StzreY =» ¥2-) do dec Sizer) 
end; 


‘we Ne 


procedure ScrollBar.SetThumbPad; 
var 
RectArr : RectOutline; 
Oldcoler 3: word; 
begin 
OldColor := Graph.GetColor; 
Graph.SetColor( GetBkColor ); 
SetViewPort( x, y, xt+SizeX, ytSizeY, ClipOn ); 
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=== draw scrollbar thumbpad ===} 
Graph.SetColor( LineColor ); 
SetFillStyle€ CloseDotFill, Color ); 
case ScrollMove of 
Vertical: SetoOutline( RectArr, 2, SPos, 
18, SPos¢+19 ):; 
Horizontal: SetOutline( RectArr, SPos, 2, 
sros+19, 18 J; 
end; {case} 
FillLPoly(€ sizeof(RectArr) div 
sizeof(PointType), RectArr ); 
=== restore default color settings ===} 
Graph.SetColort OldCotloer 7; 
RestoreViewPort; 


end; 


procedure ScrollBar.EraseThumbPad; 


RectArr >: RectOutline; 
OLdCotor =: word; 


begin 


OldColor := Graph.GetColor; 
Graph.SetColor( GetBkColor ); 
SetViewPort( x, y, xtSizex,. y+SizeyY, ClipoOn 3); 
{=== erase thumbpad ===} 
SetFillStyle(€ SolidFill, Graph.GetBkColor ); 
case ScrollMove of 
Vertical: SetOutline( RectArr, 2, SPos, 
16, §SPos#20 ); 
Horizontal: SetOutline( RectArr, SPos, 2, 
SPost19, 19 ); 
end; {case} 
FillPoly€ sizeof(€RectArr) div 
sizeof(PointTyped, ReetaArr 2: 
{=== restore default color settings ===} 
Grapn.SetColor(. OldColor ); 
RestoreViewPort; 


end; 


procedure ScrollBar.Draw; 


RectArr >: RectOutline; 
OigColer 2° work: 


begin 


OldColor := Graph.GetColor; 
Graph.SetColort LineColor 2); 
SetViewPort( x, y, x#S8izexX, y+StizeYy, ¢ttipon ds: 
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=== scrollbar outline === 
Setoutt ine (> RectArr, 15. 4,6 (S1zeXe4,¢ 81.26% -107 
SetFittistyte( soltidFill,: coteri.d; 
SetLineStyle( SolidLn, 0, NormWidth ); 
FiILLPoly( sizeof(RectArr) div 
sizeof(PointType), RectArr ); 
{=== scrollbar arrows ===} 
Graph.SetColor( GetBkColor ); 
SetiinesStylet Sotidin, 0, THICKHTEtA 2) 
case ScrollMove of 
Vertical: 
begin 
Dame (105. fies ee ee Sa 
Eine( 10,::43:- 765: 74:33 
Line® 10; 65205-16722 


Line 10, -8 eels. 4, Sizer te 23 
bine( 10, Sizgevess; 16,7. -Sit2e To 12-23 
Line<. 10, StzeY=h4;, 70, Sizev-16.2; 
end; 
Horizontal: 
begin 


tweet: @s Piss F254 oe 
EN RO Oo oT Oo tee ee ee 
Eine 435.5105: 1637) Eso 
Line( Sizex=<4,:10,°> Sizex-te, 4.) 
Line Strexk~4;,°70, Siztexk<-t2e, 16°? 
| LineC Stzek=4, 10, Sizex-16, TO 9 
end; 
end; {case} 
SetLineStyle(€ SolidLn, 0, NormWidth ); 
{=== clear scrollbar center ===} 
Graph.SetColor( LineColor ); 
SetFillStyle(€ SolidFill, Graph.GetBkColor ); 
case ScrollMove of 
Vertical: SetoutliineC: RectArr, 1, 21, 
BASSAS SIV ECT SET 37 
Horizontal: SetOutitnet : RectaArr, 21, tT; 
} S$izex-21, Si2eY-1 ); 


“ws “Se Se 


end; {case} 
FiILLPoly(€ sizeof(RectArr) div 
sizeof (PointType?, RectaArr. 2; 
{=== restore default color settings ===} 
Graph.SetColor( OldColor ); 
RestoreViewPort; 
SetThumbPad; 
end; 
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function ScrollBar.RestoreViewPort; 
begin 
with VRef do 
setViewPort( X11, ¥1, X2, Y2;,.€thees2 
end; 


function ScrollBar.GetPosition; 
begin 

GetPosition := SPos; 
end; 


function ScrollBar.GetDirection; 
begin 

GetDirection := ScrollMove; 
end; 


function ScrollBar.ScrollHit?; 
var 
Result : HitType; 
BtnStatus, XPos, YPos : integers 
begin 
Result := NONE; 
GMouse.GetPosition( BtnStatus, XPos, YPos ); 
case ScrollMove of 
Vertical: 
if€ XPos >= x ) and (€ XPos <= x+20 ) and 
( YPos >= y ) then 
if YPos <= y+20 
then Result := UP else 
if YPos <= y+SizeY-21 
then Result := VBAR else 
if YPos <= y+tSizey 
then Result := DOWN; 
Horizontal: 
if€ YPos >= y ) and (¢ YPos <= y+20 ) and 
( XPos >= x ) then 
if XPos <= x+20 
then Result := LEFT else 
if XPos <= x+S$izeXx-21 
then Result := HBAR else 
if XPos <= x+SizexX 
then Result := RIGHT; 
end; {case} 
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{ 

{ 

{ 

{ 440 YPos >=: y ) and © YPRos. <= yr20. 2° then 

{ if¢€ XPos >= x ) and ¢ XPos <= x+#20 ) 

{ then Result := LEFT else 

{ if€ XPos >= x+SPos ) and ( XPos <= x+SPos+20 ) 
{ then Result := HBAR else 

{ if€ XPos >= x+SizexX-20 ) and ( XPos <= x+Sizex ) 
{ then Result := RIGHT; 

{ 


if Result <> NONE then 
begin 
GMouse.Show( FALSE ); 
EraseThumbPad; 
end; 
case Result of 
LEFT, UP: dec( SPos, Step ); 
HBAR: SPos := XPos = ( x # 10 ) 
VBAR: SPos := YPos —- € y + 10 ) 
RIGHT, DOWN: inc(€ SPos, Step ); 
end; {case} 
1¢€ SPos < 21) then SPos 32 213 
case Result of 
LEFT, HBAR, RIGHT: 
1FLSPos >: SizeX=-41.). then Sos 
UP, VBAR, DOWN: 
if€ SPos > SizeY-41 ) then .S$Pos 
end; {case} 
if Result <> NONE then 
begin 
SetThumbPad; 
GMouse.Show( TRUE ); 
end; 
ScrollHit := Result; 
end; 


=e Ne 


Sizex-41; 


SizeY-41; 


end. 
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(SSSsesse2seeee5eee22ese2e====} 
{ ScrlTest.PAS } 
{ demonstrates scrollbars } 
(S=SSSSSSSSeeeeee5eeeee2====} 


uses Crt, Graph, Mouse, Button4, ScrlBar; 


var 
TMouse : TextMouse; 
mButton : Position; 
Exit, Status : Boolean: 
GDriver, GMode, GError, 
i, j, SButtons, BtnCount : integer; 


var 
HSCcroll, VSeroett ¢ Seretigares 
ExitButton =: Button; 


begin 
GDriver := Detect; 
InitGraph(€ GDriver, GMode, '\TP\BGI' ); 
GError := GraphResult; 
1f GError <> grOk then 
begin 
writeln(€ 'Graphics error: ', GraphErrorMsg(GError) ); 
writeln« "program aborted..." ds 
Rattcts: 
end; 
GMouse.Reset( Status, BtnCount ); 
if Status then 
begin 
ClearDevice; 
EXiIt = FALSES 
GMouse.Initialize; 
HScroll.Init(€ 0, GetMaxY, GetMaxX-60, 
Green, LightGreen, Horizontal ); 
VScroll.Init(€ GetMaxx, 0, GetMaxyY, 
Green, LightGreen, Vertical ); 
with ExitButton do 
begin 
La? eZ 
SetButtonType( Rounded ); 
Create( HScroll.Position-10, VScroll. Position, 
S0, 20, White, “eat: 
end; 
repeat 
GMouse.QueryBtnDn( ButtonL, mButton ); 
if mButton.opCount > O then 
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begin 
if ExitButton.ButtonHit( mButton.XPos, 
mButton.YPos ) 
then Exit := TRUE else 
repeat 
case HScrott.ScroltlHit of 
LEFT, HBAR, RIGHT: 


ExitButton.Move( HScroll.Position-10, 


VSerott Post tion 3; 
end; {case} 
case VScroll.Serol ltt -of 
UP, VBAR, DOWN: 


ExitButton.Move( HScroll.Position-10, 


Vecrott. Poa tTtion: 23 
end; {case} 
GMouse.QueryBtnUp( ButtonL, mButton ); 
until mButton.opCount > Q; 


end; 
until Exit; 
end; 
CloseGraph; { restore text mode and } 
TMouse. Initialize; { reset mouse for text operation } 


end. 


Chapter 34 


Dynamic Object Instances 


All of the objects used so far in demo programs have been static instances; that is, 
instances of object types listed in the var declaration and statically allocated in the 
program's data segment and stack. References to static instances (or static objects) 
have no connection with the type of methods, static or virtual, that belong to the 
objects in question. 

Static allocation is restrictive and cumbersome. With conventional record data 
structures, static allocation requires the determining of the maximum number of 
records that will be required at the time the program is written, and then the 
declaring of an array of records of the anticipated size. Of course, the traditional 
64K data size limit has also been an unacceptable restriction for many applications. 

More often, static record allocation is replaced by dynamic record allocation 
where memory pointers are used as reference links and where memory is dynam- 
ically allocated for data records as needed and deallocated when no longer wanted. 
This frees unnecessary memory for other uses. 


Advantages of Dynamic Objects 


Object instances, which are closely related to data records, can also be dynamically 
created, allocating memory as required, destroying the object and deallocating the 
memory when it is no longer needed. In this fashion, an application can create— 
within system memory limitations—as many objects as necessary and then release 
these from memory when they are no longer needed. 
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Obviously, for the Button or ScrollBar objects used in previous demonstrations, 
requirements for unanticipated numbers of objects are unlikely. Instead, in Chapter 
35, a data record object type will be used to demonstrate dynamic object allocation 
in circumstances where prediction of the number of objects is not possible. 

First, however, it will help to understand how objects are created using pointer 
references and dynamic memory allocation. 


Pointers to Objects 


Before dynamically creating an object instance, a handle or pointer to the object is 
necessary; otherwise, the object instance could not referenced or called by the 
application. An object instance can be allocated as a pointer referent using the New 
procedure: 


var 
PHSerotlh +. -*%&8erotllBar; 


New(€ PHScroll ); 


Just as with a data record, the New procedure dynamically allocates sufficient 
memory space on the heap to contain an instance of the ScrollBar object—according 
to the size of the ScrollBar base type—and returns the address of the memory space 
allocated to the PHScroll pointer variable. 

Since the ScrollBar object contains virtual methods, the Init method must be 
called for the constructor call as well to create the scrollbar image: 


PHScroll*.Init( 0, GetMaxY, GetMaxX-60, 
Green, LightGreen, Horizontal ); 


After this, all method calls are made in the normal fashion except for using the 
pointer name and the caret (*) reference symbol in place of the instance name, 
which would have been used with a statically allocated object instance. Instead of: 


case: HScroil. serottwit oT 
the method is called as: 
case PHScroll*.ScrollHit of 


Grouped references can still be made to several methods as in the following 
example: 


with PHScrott*: do 
begin 
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case ScrollHit of 


end; {case} 

SSQtTLOGt “iis FF 
end; 

The method calls internal to the object definition, of course, do not require the 
pointer referent and no changes to object definition units are required. 


Allocation and Initialization 


Beginning with Turbo Pascal 5.5, the syntax of the New procedure has been 
extended, allowing allocation and initialization of an object to be executed in a 
single operation: 


New€ PHScroll, Init(€ 0, GetMaxY, GetMaxXx-60, 
Green, LightGreen, Horizontal ) ); 


This extension of the New procedure (allowing New to be called with two 
parameters; the pointer variable as the first and the constructor invocation as the 
second) provides both convenience and a more compact program structure. 

Obviously, for a pointer object, the constructor method (Init) cannot be called 
before the object is allocated by the New procedure because the instance being 
initialized does not exist yet. Instead, with New’s extended syntax, the Init con- 
structor performs the dynamic allocation via special entry code that is generated 
as part of a constructor’s compilation, while the type of pointer passed as the first 
parameter tells the compiler which Init method to call. 


A Second Extension for New 


The New procedure has been extended in a second fashion too, allowing New to 
act as a function returning a pointer value. Used in this fashion, the calling 
parameter for New is the pointer type instead of the pointer variable: 
type 

SPtr = “S¢erottBar; 


var 
PHScrait © $?trz 


PaHScrollt += Newt SPtr 22 


In this form, the New procedure can be used with the object’s constructor as it 
was previously: 
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PHScroLll := New( SPtr, Init( 0, GetMaxY, GetMaxX-60, 
Green, LightGreen, Horizontal ) ); 


Note that this extension to the New procedure applies to all data types—not 
merely to object types—and the same format can be used; for example, with file 
data structure: 
type 
FPtr = “FileRec; { record type from Dos unit } 


var 
PETte: ce Frtr? 


PFile := New FPtr ); 


Disposing of Dynamic Objects 


Traditionally, data records are deallocated using the Dispose procedure when no 
longer required: 


Dispose(€ DataItem ); 


For a dynamic object, there may be more required for disposal than simply 
releasing the heap space. This is because an object may contain its own pointers to 
other dynamic structures or to objects that also need to be released or that require 
special clean-up methods such as closing open files or restoring file records before 
exiting. 

Instead of simply calling the Dispose method directly, complex objects should 
include a clean-up method, or multiple clean-up methods, to handle the special 
shutdown tasks. The Turbo Pascal OOP Guide suggests the standard identifier 
Done be used for such shutdown methods, just as Init is used as the standard 
constructor method name. This suggestion will be followed here. 


The Destructor Method 


Turbo Pascal 6.0 has provided a special method type—identified by the keyword 
destructor—which is used to clean up and deallocate dynamic objects. Unlike the 
constructor method call, the destructor call by itself does nothing directly to 
deallocate memory. Instead, the destructor method provides the means by which 
a program can combine a shutdown and clean-up method call with a Dispose 
instruction. 
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However, before going into the details of what the destructor call accomplishes 
and how, explanations will be simplified by looking first at how the destructor call 
is used. 


Programming Destructor Methods 


Using the ScrollBar object from Chapter 33 as an example, a destructor method 
could be declared as follows: 
type 
ScrollBar = object( Button ) 

ScrollMove : Direction; 

LineColor, SPos, Step : integer; 

VRef : ViewPortType; 

constructor THE HPs, PLY, Size, tt, Ce © tuntecer: 

Orientation. :. B03. rection 3; 
destructor Done; virtual; 
procedure Setioe CoPtxk,: Rty nt tateger di: virtual ; 


wia's 
The destructor method, Done, might be implemented as follows: 


destructor ScrollBar.Done; 
begin 

Erase; 

ResortViewPort; 
end; 

In this case, the Done method calls the Erase method (which is inherited from 
the Button object type) to erase the scrollbar image. Because the Button object resets 
the viewport (graphics window) to the entire screen, the Done method finishes its 
task by calling RestoreViewPort to restore the graphics window parameters that 
were originally found when the scrollbar was created. 

Alternatively, the Done method—like the Init method—could be an empty 
procedure: | 


destructor ScrollBar.Done; 
begin 
end; 

In other applications, a much more complex Done method may be desired—or 
more than one Done method—may be desired to execute different clean-up tasks. 
Unlike the constructor method type which normally needs only one version, it is 
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practical for an object to have more than one destructor method, though only one 
destructor method can be called for any object instance. 

Also, as with other methods, destructors can be inherited and may themselves 
be either static or virtual methods. Because each object type will generally require 
custom clean-up handling, it is recommended that destructors should always be 
virtual methods in order to ensure that the correct shutdown handling is called for 
each object type. 


Using the Destructor Method 


The destructor method is used in two different fashions, depending on whether the 
object instance is a static instance or was dynamically created. Because the destruc- 
tor method is primarily concerned with dynamic object instances, these will be 
shown first. The simplest way to show how a destructor is used, is by example: 


New(€ PHScroll, Init(€ 0, GetMaxY, GetMaxX-60, 
Green, LightGreen, Horizontal ) ); 


Dispose( PHScroll, Done ); 


For dynamic instances, both the instance allocation (using New) and the 
deallocation (using Dispose) are handled by the application, not by the unit where 
the object type is defined (assuming, as is usually the case, that the object is defined 
separately from the calling application). 


Destructor Calls and Static Instances 


The destructor method identifier is not necessarily required for shutdown handling 
because the destructor method definition applies only to dynamically allocated 
objects to ensure that proper memory deallocation is executed. Destructor methods 
can also be used with statically allocated instances without incident or error: 


var 
HSerot’ +: ScrolUBar: 


HScroll.Init(€ 0, GetMaxY, GetMaxX-60, 
Green, LightGreen, Horizontal ) ); 


HScroll.Done; 


In this case, the Done method is called for a static instance of ScrollBar and, as 
a result, the scrollbar image will be erased from the screen and the viewport settings 
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will be restored, however, no memory deallocation is attempted. Here, the special 
properties of the destructor method call are not required and they do nothing. 

Ergo, all object types can be supplied with destructor methods and, since you 
cannot predict that any object type will or will not eventually be used as a dynamic 
object, the best choice is to declare a destructor method for all object types. 


The Destructor Mechanism 


The destructor method is designed as a special method type for use principally with 
dynamic object instances and with polymorphic objects (see also Extended Type 
Compatibility), allowing dynamically allocated objects to be discarded or 
destroyed, releasing the memory used by the object for further use. 

Before memory can be deallocated, however, the Dispose procedure needs to 
know not only where the memory should be released, but also how much memory 
should be released. 


The Dispose Procedure 


The Dispose procedure, like the New procedure, has been given an extended syntax 
in Turbo Pascal 6.0, allowing Dispose to accept a second parameter that specifies 
the amount of memory to be deallocated. 

In conventional programming, the Dispose procedure is called as: 


type 

str ¢ String; 
var 

Ptr € “Str: 


New( Ptr ); 
Ptr* := 'Now is the time for all good computers ...'; 
Dispose( Ptr ); 


In this example, the Dispose procedure gets the size of the variable indicated 
by Ptr directly by looking at what Ptr indicates. 

With objects, the sizes of object types vary tremendously. With polymorphic 
objects, the object identifier does not necessarily indicate the size of the allocated 
instance. 

For this reason, the destructor offers the solution by accessing the object 
instance’s Virtual Method Table. Each object type’s VMT includes the size, in bytes, 
of the object type definition. The VMT for any object is available through the Self 
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referent—an “invisible” referent which is passed to a method on any method call, 
providing a handle or address to the object type’s Virtual Method Table. 

When the destructor method is called, it returns the size indicated by the object 
type’s VMT which is the size of the actual object instance. Even if the object instance 
is a polymorphic object where the object name no longer identifies the actual object 
instance, the instance’s correct VMT is accessed and the appropriate instance size 
is still returned: 


New(€ PHScroLll, Init(¢ O, GetMaxY, GetMaxXx-60, 
Green, LightGreen, Horizontal ) ); 


Dispose( PHScroll, Done ); 


The Done destructor method, after calling the ScrollBar VMT, returns the size 
of the object instance to the Dispose procedure, ensuring that the appropriate 
memory deallocation is executed. 

Note: the task of returning the instance size is not accomplished by the body of 
the destructor method, but by an epilog code generated by the compiler in response 
to the reserved word destructor. 


Extended Type Compatibility 


Turbo Pascal implements extended type compatibility rules that allow any object 
instance to be assigned to a variable of an ancestor object type. These are known as 
polymorphic objects. 

Following the example object types used so far, an instance of object type 
ScrollBar can be assigned to a variable of type Point. In like fashion, a pointer to a 
variable of type Point can become a pointer to an instance of type ScrollBar. 

Extended type compatibility will be used in later examples as pointers of an 
ancestor object type, List. The printers are assigned to a variety of descendant object 
types to create a mixed list of record object types. 


Summary 


In this chapter, two extensions to familiar Pascal procedures have been intro- 
duced—the extended New and Dispose procedures—and the theory of creating 
and handling dynamically allocated object instances has been discussed. A final 
graphics example, revising the ScrlTest.PAS program to use dynamic object 
instances is shown below. 
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In Chapter 35, these techniques will be demonstrated further, together with 
handling practices for pointers and pointer-linked lists to create a multipurpose 
address/telephone directory and to create special methods allowing a linked list 
to conduct its own sorting operations, as well as other custom activities. 


{sas SSeeSseeSseseSetseseseSSeeeressessesecs=czz} 
{ SerlTst2.PAS } 
{ uses dynamically allocated ScrollBar objects } 
ee ee 


uses Crt, Graph, Mouse, Button4, ScrlBar; 
var 

PAScrelt, PYVScrotl : “Serolitsaer ; 
ieee 


New(C PHScroll, Init( 0, GetMaxY, GetMaxx-60, 
Green, LightGreen, Horizontal ) ); 
New( PVScroll, Init(¢ GetMaxX, 0, GetMaxY, 
Green, LightGreen, Vertical ) ); 


Create( PHScroll*.GetPosition-10, 
PVScroll*.GetPosition, 
eq. 20, Cianteed, “txt 3; 


case PHScroll*.ScrollHit of 

LEFT, 

HBAR, 

RIGHT: ExitButton.Move( 
PHScrolLl*.GetPosition-10, 
PVScroll*.GetPosition ); 

end; {case} 
case PVScroll®*.ScrollHit of 
UP, 

VBAR, 

DOWN: ExitButton.Move( 
PHScroll*.GetPosition-10, 
PVScroll*.GetPosition ); 

end; {case} 


uUnETA EXees 
Dispose( PHScroll,Done ); 
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Dispose( PVScroll,Done ); 
end; 


Chapter 35 


Binary Tree Objects 


In an earlier, non-object-oriented example, data was handled using pointer struc- 
tures in a linearly-linked list. In this example, the linear list will be replaced by a 
binary-tree object. Here, the organization of the data is—if confusing at first—faster 
both to sort and to access than in a linear structure. For additional information on 
the theory of tree structures in general, see Algorithms and Data Structures by Niklaus 
Wirth. 

Binary-tree structures (called B-Trees or simply Tree structures) are generally 
recognized as the most efficient data structures possible for general applications. 
In some specialized cases, where the structure and arrangement of the data itself is 
highly predictable and ordered, other organizational structures may be more 
efficient, but these are exceptions. 

Also, binary-sorts are actually more efficient when the source of the data is 
disordered than if the data source is already ordered or alphabetized; though, in 
either case, the binary sort is usually more efficient than a linear sort routine. 


Binary Tree Structures 


A binary tree structure is simply a data structure in which each element has two 
links to other elements and the elements are linked together in specific relation- 
ships. As an example, Figure 35-1 shows a binary tree created from the integer list: 
6,3; 4, 2,8, 12, 11,3, 1,9; 7,48. 
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The rule ordering in this binary tree is very simple—smaller to the left, greater 
to the right—and the tree grows according to the order in which the data elements 
were added to the tree. Starting with 6 which forms the root of the tree, 3 is added 
to the left (smaller) and then 4 begins by taking the lesser (left) branch from 6 and 
then the greater (right) branch from 3. 


Figure 35-1: A Binary Tree of Integers 








Each subsequent integer entry searches for its own appropriate position within 
the growing structure. Note that binary trees are usually illustrated upside down, 
beginning with the root at the top. 

Notice that, when the tree is built, at no time is any established link changed to 
favor a newer entry. Therefore, 10 begins at the root, is greater than 6, is greater than 
8, is less than 12, is less than 11 and finally, finds its place as greater than 9. 

If the resulting tree appears confusing, consider how easy it is to locate any 
element in the tree. To locate the highest entry in the tree, for example, simply begin 
at the root, follow the greater (right) path and, after the third step, the entry 12 is 
located and identified as the greatest element in the tree. In a linear arrangement, 
this same result would require four times longer to accomplish. 

Any element in the tree can be found in the same fashion. 
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Binary trees are not limited to numerical or alphabetical data lists. Instead, a 
binary tree can be created for any type of data for which a relationships can be 
described. For a second example, consider the formula—(a +b /c)-(d*e+f)— 
and the binary tree representing the values and operations involved (Figure 35-2). 


Figure 35-2: A Binary Tree for a Formula 














In this structure, all variables (numerical values) are found at the ends of 
branches and all non-terminal nodes indicate operations. Notice also that the 
parentheses in the written formula do not appear in the binary tree. Instead, the 
groupings are implicit in the structure of the tree. 

One simple application for a tree of this type might be a program to solve 
algebraic equations that were entered by the user in the text form similar to the 
preceding example. 

Since the formula entered could take many different forms, any predefined 
structure would have to be unnecessarily complex to accept all of the possibilities. 
By using a binary tree structure similar to the one illustrated, any formula can be 
represented as a series of binary relationships. 

A program using this structure would begin by finding the extremities of the 
tree; for example, beginning with the d and e elements, executing the * operation 
indicated by their mutual root, then replacing the operation with the resulting value 
and discarding the two terminal nodes. 
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By operating recursively on each branch until no subnodes remain, the root 
contains the final result of the formula. (Which is essentially how most program- 
ming languages handle formula processing in the first place.) 

Naturally, if the formula is to be solved repeatedly for different values, instead 
of discarding nodes, the application would simply examine each node to see if it 
contained a value or only an operator, searching further if the node contained a 
solution. 

Other, more familiar, examples of binary tree structures would include family 
genealogies, basketball or tennis tournaments, or race horse pedigrees. 


A Binary Tree Application 


In Figure 35-3, a data list is shown in a binary-tree using an alphabetical relation- 
ship. In this case, the tree is turned sideways (root element at left) and the numbers 
by each entry show the order in which the elements are read from the data file. This 
is a sample of the binary tree structure that will be created by the PhonTree program 
demonstrated in this chapter. 

Before going into the intricacies of programming a binary tree structure, table 
35-1 shows a time comparison between the linear entry-sort algorithm used in the 
earlier, non-object-oriented example and the binary sort which will be demon- 
strated here. 


Table 35-1: Comparing Disk Read, Sort and Display Times 





linear sort. .binary tree. 
File access time (16 items): 0.02060 seconds 0.02060 seconds 
Sort operations (16 items): 0.00955 seconds 0.01071 seconds 
Screen write (21 lines): 0.03680 seconds 0.01220 seconds 
Total: 0.06695 seconds 0.04351 seconds 


Operation times derived by averaging elapsed time for loop = 1..1000. 


For the relatively short data list used in this example, the binary sort operations 
required a bit more time than the linear sort operations. For longer lists, when time 
becomes a real factor, the time requirements of the binary sort will be considerably 
shorter than for a linear sort with the discrepancy increasing as the number of 
handled entries grows. 

This discrepancy is produced, in part, by the fact that both sort times include 
the time required to dispose of the data elements. For the linear sort, the dispose 
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time itself is relatively short compared to the time required to build the list because, 
for disposal, the linear list simply begins at the top and works down without regard 
to the order of the list—in this example, requiring approximately '720 of the time 
for disposal as was required to build the tree. 


Figure 35-3: An Alphabetical Tree 
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In order to accomplish disposal of the elements, the binary tree, has to execute 
essentially the same operations as were required to build the tree, retracing each 
branch and requiring equal time for both tasks. 

However, the difference in execution speeds may be more obvious by looking 
at the Screen write times. Here, even though the linear sort is already ordered and 
has accomplished the screen write by stepping down an alphabetical list, the binary 
tree is still faster. It even uses a recursive process to search the tree for the proper 
order in which to write the data out to the screen. 

In large part, of course, the times are a product of how each version of the 
program has compiled and, to some degree, it reflects the strengths of the Turbo 
Pascal compiler. The bottom line for application programming is not the theoretical 
speed of a system, but the actual real-time/real-world speed with which an 
application operates. 

In the real world, data lists are not necessarily disordered; therefore, what 
happens when the data set is already in alphabetical order? 

A third set of operation times appear in Table 35-2 using the same data list 
contents, but with the data entries pre-arranged in alphabetical order. 


Table 35-2: A Binary Sort with Ordered and Disordered Sources 


disordered. ordered. 
File access time (16 items): 0.02060 seconds 0.02060 seconds 
Sort operations (16 items): 0.01071 seconds 0.01895 seconds 
Screen write (21 lines): 0.01220 seconds 0.01219 seconds 
Total: 0.04351 seconds 0.05174 seconds 


Interestingly, the sort operations for the pre-ordered list have actually taken 
longer than for the randomly ordered list. This is not an unexpected outcome 
however, because in this case, the binary tree result is the analog of a linear list and 
each subsequent element to be sorted has to step further down the tree to find its 
proper place than it did with a randomly ordered data set. The results are, even so, 
still faster than for the linear sort procedure. 

You may also notice that the screen display time for the ordered list is faster— 
‘710,000 of a second—than for the disordered list, reflecting the difference in the 
number of recursive steps required to display the list in proper order. Most of the 
time required for the screen display is simply the time required to write the data to 
the video memory. 
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With either an ordered or disordered source, the handling time for the binary 
tree is significantly faster than for a linear listing. 


Implementing a Binary-Tree Object 


The PhonTree program uses an instance of LinkObj to create a tree of DataObj. But, 
unlike the linear examples shown previously, PhonTree will use recursive handling 
and the LinkObj definition provides binary instead of linear linking. 
type 
NodeRec = record 
Root, Prev, Next : NodePtr; 
Ltem 2: Batartrs end; 

In an earlier example, each data record incorporated two pointers, Prev and 
Next which were used to create a chain. In this case, Prev and Next no longer point 
up and down the list, but point to elements that precede or follow the current 
element while the Root pointer points back to the root element of the current node 
or toward the root of the tree. 

Also, where the original list could have been constructed with a single pointer 
linking the list only one way; for the binary tree, at least two links are essential and 
the third link, Root, will be necessary later before an item can be deleted from the 
tree without destroying the tree. 

LinkObj includes two methods, Add and Done, which incorporate sub- 
procedures, BuildTree and Disposeltem. Where these object methods can not 
conveniently call themselves recursively to automatically traverse a tree, the meth- 
ods can call private subroutines which can call themselves recursively. Later, 
however, the PrintList method will call itself recursively without needing a subrou- 
tine. 

LinkObj = 

object 
Nodes : NodePtr; 
constructor Init; 
destructor Done; virtual; 
procedure Add( ThisItem : DataPtr ); 
procedure ReadFile€ NameFile: string ); 
procedure PrintList( ItemPtr: NodePtr); 
function Find( RefLink : NodePtr; 

SearchStr : string 2: NodePtr; 
function FindPartial( RefLink : NodePtr; 
PartiatStr : string ): NodePtr; 
end; 
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Notice also that the LinkObj definition does not include a data structure, only 
the NodePtr pointer structure, because the data is handled by a different object type: 
DataObj. 


Building the Tree 


LinkObj’s ReadFile method accesses the data file (or files), calling the Add method 
with each entry. 


procedure LinkObj.Add; 


var 
NPtr : NodePtr; 

begin 
New( NPtr ); 
NPtr* Reet’ te nit; 
NPtr* Wext ss] nits: 
NPG? Prey fs nits 
NPtr*.Item := ThisItem; 


In this case, LinkObj.Add initializes all three node pointers as nil because, if 
not, unassigned pointers could, quite easily, clobber the stack the first time the 
program executes. When this happens, even though the program may execute 
correctly once, a system reset may be required afterwards before the program (or 
some other program) can operate again. 

With this caution stated, the Add method proceeds by determining if the 
current entry is the first entry read. 

1f Firstlink = att 

then FirstlLink := NPtr 


else BuildTree( FirstLink, NPtr ); 
end; 


If this is not the first entry, then the dynamic pointer to the current entry (NPtr) 
and the static pointer to the root entry (FirstLink) are passed to the BuildTree 
method for more handling. 

The reason the Add method now uses a subprocedure instead of handling 
everything, is that PhonTree’s handling will be recursive and the BuildTree sub- 
procedure can call itself recursively, which the Add method cannot. 


procedure BuildTree( RefLink, NewLink: NodePtr ); 
begin 
if Precede( NewLink*.Item*.Data.Name, 
RefLink*.Item*.Data.Name ) then 
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As in previous examples, BuildTree begins by calling the Precede function to 
determine the order of the current and reference entries. 


begin 
if RefLink*%.Prev = nil then 
begin 
RefLink*.Prev := NewLink; 
NewLink*. Root := RefLink; 
end else BuildTree( ReflLink*.Prev, NewLink ); 
end else 

If the current entry precedes the reference entry, the next question is if the 
reference link’s .Prev is already linked or if it is nil (empty). 

If the latter case is true, then the new entry can be linked directly. If not, then 
BuildTree is called recursively using the reference link’s .Prev pointer to step down 
the tree structure. If the current entry does not precede the reference entry, the same 
determination is made for the reference link’s .Next pointer and the current item is 
either linked here or a recursive call is made to step down the tree until the 
appropriate location is found. 

begin 
if RefLink*.Next = nil then 
begin 
RefLink*.Next := NewLink; 
NewLink*’*. Root := RefLink; 
end else BuildTree( RefLink*.Next, NewLink ); 
end; 
end; 


Disposing of the Tree 


After building the tree, the next most important task is disposing of the tree. 
Remember, memory is being dynamically allocated for each item in the tree and, 
unless provisions are made to properly dispose of this memory, a lot of the available 
RAM can wind up allocated for defunct purposes and not available to other 
applications even after the current program has terminated. 

destructor LinkObj.Done; 


procedure Disposeltem( ItemPtr : NodePtr ),; 
begin 


end; 
begin 

DisposeItem( FirstLink ); 
end; 
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For the binary tree recursive handling is again required. Therefore, Done calls 
its own subprocedure, Disposeltem, with the static pointer, FirstLink. 

The Disposeltem procedure is multiply recursive but begins with a test to 
determine if the current entry is nil and, if so, does nothing since nothing needs to 
be done (i.e., the end of a branch has been reached—that’s all). 


procedure DisposeItem( ItemPtr : NodePtr ); 
begin 

if ItemPtr <> nil then 

begin 

If ItemPtr is not empty, then the next step is to test the .Prev pointer. If this link 
points anywhere, then Disposeltem is called recursively to travel down this branch. 


if ItemPtr*.Prev <> nil 
then DisposeItem( ItemPtr%*.Prev ); 


The same test is then executed for the .Next pointer, again calling Disposeltem 
recursively if necessary. 


1f ItemPtr*.Next <> nit 
then DisposeItem( ItemPtr*.Next ); 


After disposing of the Next and Prev branches, the current entry’s data ele- 
ments, indicated by .Item, need to be handled. 


1T DTteattr® il tem <> wit | 
then Dispose( ItemPtr*.Item, Done ); 


Finally, the pointer itself, has to be disposed of: 


Dispose( ItemPtr ); 
end; 
end; 


Printing the Tree 


While building the tree and disposing of the contents after use are important, it also 
helps to be able to do something with the records in between. Even though the 
structure of the data is very different from the previous linear examples, the data 
will be displayed in essentially the same fashion—in alphabetical order. 

This is quite easily accomplished here by making the PrintList method itself a 
recursive procedure. 
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The PrintList method is initially called with the static pointer FirstLink and, 
thereafter, calls itself recursively until the entire list has been written to the screen. 


procedure Link0Obj.PrintList; 
begin 
if ItemPtr <> nil then 
begin 
As with the Disposeltem method, PrintList begins by checking the current entry 

to see if it is empty. Assuming the entry is not empty, PrintList checks first to see if 
there are any items that preceded the current item. This is not done by calling the 
Precede function, but by checking the .Prev pointer and calling itself recursively to 
handle any prior entries. 


if ItemPtr*.Prev <> nil then 
PrintListt Ptenrer*. Prey. 273 


Only after checking the .Prev pointer is the current entry listed by calling 
DataObj’s Print method. 


with ItemPtr*%.Item* do Print; 


After handling any prior items and the current item, the following items are 
handled, again by testing the .Next pointer and, again, calling PrintList recursively. 


if ItemPtr*.Next <> nil then 
PrintList( ItemPtr*.Next 2); 
end; 
end; 


Binary Searches, Insertions, and Deletions 


While the current program does not do searches or insert and delete items from the 
tree, methods are provided for two of these purposes: searching and deleting. 

For inserting new items in the tree however, unlike linear-lists, no special 
provisions are required because the same method used to build the tree is used to 
add new items and new entries are always made at an existing free node instead 
of attempting to insert the new element within the existing structure. 


Searching a Binary Tree 


Searching a binary tree is different than searching a linear list and, for this purpose, 
two methods—Find and FindPartial—are provided. 
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The Find method is called with two arguments; the static pointer, FirstLink, and 
a string argument to be located. It returns a pointer to the located entry or a nil 
pointer if the entry is not found. The Find method, however, requires an exact match 
beginning at the first of each Name field though the search string can be only part 
of the name field. 

The FindPartial method is called in the same fashion as the Find method, but 
will attempt to find a match for the search string anywhere within the Name field, 
not merely beginning from the first of the field. 

Of course, the FindPartial method searches the entire binary tree until a match 
is found while the Find method searches the tree according to where a matching 
entry should occur. And the trade-off here is that the Find method is faster, but the 
FindPartial method is more accurate (and more forgiving of human foibles). 

Note: the program listing at the end of this chapter shows one way that these 
two methods might be used in combination, using the Find method first for speed 
and then FindPartial second for accuracy. 


The Find Method 


The Find method searches recursively, looking for an exact match for the search 
string beginning at the first of the Name field. 


function ‘Link0ObBj].Find: 
var 
Result : NodePtr; 


function Match Str  Str2é 2:-string 2: boolean: 
begin 


end; 


The Match function used by the Find method simply compares two strings, 
disregarding case, to determine if the strings match. It returns a boolean result. 
begin 

Result := nil; 
if RefLink <> nil then 


if Match(€ SearchStr, RefLink*.Item*%.Data.Name ) 
then Result := RefLink else 


The Find method begins by testing the current item for a match. If a match is 
found, then the RefLink pointer is returned to the calling function. 
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If no match is found, Find compares the search string with the current name 
field to decide if the search string would precede or follow the current entry within 
the tree structure, then calls itself recursively. 


if Precede( RefLink*%.Item*.Data.Name, SearchStr ) 
then Result := Find( ReflLink*%.Next, SearchStr ) 
else Result Find( RefLink*’.Prev, SearchStr ); 
Find := Result; 
end; 


The FindPartial Method 


The FindPartial method searches the entire binary tree and identifies a match for 
the search string anywhere within the Name field, returning a pointer to the first 
matching entry found. 


function LinkOb}.FindPartial; 
var 
Result : NodePtr; 


function Matcht Strit, Stra.) etethig: 2: boolean: 
begin 


end; 


The Match function used by the FindPartial method converts both strings to 
uppercase before executing a comparison, then uses the Pos function to determine 
if the search string occurs anywhere within the Name field, again returning a 
boolean result. 
begin 

Result := nil; 
if RefLink <> nil then 
begin 
if RefLink*.Prev <> nil then 


Result := FindPartial( RefLink*’.Prev, 
Partial str 3s 


Find Partial executes recursively in order to begin at the alphabetical top of the 
binary tree and searches down until a match has been found. 

If a match has been found and, therefore, the Result pointer is no longer nil, 
there’s no point checking the current Name field. Otherwise, the local Match 
function is used and, if a match occurs, Result returns the RefLink pointer. 
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if Result = nil then 
if Match( PartialStr, RefLink*.Item*%.Data.Name ) 
then Result := RefLink; 


If Result is still nil, FindPartial continues recursively down the tree. 


if Result = nil then 
+f RefFEI NK Next> <> nit: then 
Result := FindPartial( RefLink*.Next, 
Pertiatstr 2; 
end; 
FindPartial := Result; 
end; 


If no match has been found, then a nil result is returned to the calling procedure. 


Removing an Item from the Tree 


The Deleteltem method is used to remove a specific entry from the binary tree, but 
obviously, before an item can be deleted from the tree, provisions to locate a specific 
entry were needed and have been supplied by the Find and FindPartial methods. 

Of course, the real trick is not deleting an entry from the binary tree structure, 
but doing so without losing other elements that were linked to the deleted item—kind 
of like cutting out the center of a tree branch without cutting off the limb. 

One method that could be used would be to delete the data element while 
leaving the node element in place. This will work, but itis hardly an elegant solution 
and could leave a lot of useless, empty nodes within the tree. A better method is to 
remove both the data and node elements, relinking the affected portions of the tree. 
Figure 35-4 shows an entry being deleted from the tree. The affected links are shown 
as heavy lines. 

Now, as you can see, after deleting the Novation entry, the L-5 entry has one 
free pointer but both the Sextant and NEC entries are left dangling with no 
connections to the rest of the tree. Obviously, only one of these can be linked back 
to the L-5 node, so the question becomes which branch takes the immediate link 
and where does the other branch reconnect. 

The choices are not completely arbitrary because there are restrictions that need 
to be observed to preserve the ordering of the tree. 

In the illustrated example, since the L-5 node’s free link is a Next pointer, the 
obvious choice is to reconnect the Novation node’s Next link, maintaining the 
correct ordering. 
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Figure 35-4: Deleting an Element 












Novation 


Figure 35-5: Relinking After Deletion 
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Now, the NEC node was previously connected to a Prev link so a new Prev link 
is needed to reconnect and this is done simply by stepping down this branch of the 
tree until a free Prev pointer is found. The results for this branch of the binary tree 
are shown in Figure 35-5, again with the new links appearing as heavy lines. 

If the broken link to the main body of the tree had been a Prev pointer, then the 
descendant Prev link, if any, would have been reconnected first and the remaining 
branch stepped down until an empty Next pointer was found. 

The fact that this will always result in a correct ordering is not entirely obvious, 
but it should become clear if you will consider for a moment how entries are added 
to the tree. 

Any entry that followed the L-5 entry, but would have preceded the Novation 
entry, would have originally connected to the tree either at the NEC entry or further 
along this branch and could not have been found on the Sextant branch. Therefore, 
everything on the NEC branch must precede all entries that are descended from 
Sextant and all entries that are descended from the Sextant node must be lower than 
entries on the NEC branch. 

Now, if you are not completely confused (try drawing a few examples for 
yourself—unless you make an error, you will find this ordering correct), there still 
remain special cases where the preceding handling is not sufficient. 

First, if the deleted item is linked to only one subbranch—which can be either 
a Prev or Next link—this single link is reconnected to the deleted item’s root node. 

Second, if the deleted item is the end of a branch and has no dependent links 
then the deleted item’s root must be set to nil. 

Last, if the deleted item is the root of the binary tree, the static pointer FirstLink 
must be updated to point to the new root element. 


The Deleteltem Method 


The requirements and conditions described preceding make the Deleteltem 
method a relatively complex if..then..else decision tree; at least, complex compared 
to the other methods used here. 


procedure LinkObj.DeletelItem; 
var 
APtr, BPtr = NodePrtr; 
begin 
APtr 2= TtemPtr: 
if APtr = FirstLink then 
TY: FIP StL ink’. Prav «Fn tt 
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then FirstLink := FirstLink*’.Prev 
else FirstLink := FirstLink*’.Next; 


The Deleteltem method uses two static pointers, imaginatively named APtr and 
BPtr, to track positions through the binary tree. APtr begins by taking the pointer 
links of the item that will be deleted and then handles the first special case: is the 
current pointer the root of the entire tree? 

If so, then FirstLink is moved to either the Prev link or, if there is no Prev link, 
to the Next link. 

Of course, if the tree is empty except for this root item, then there is neither a 
Prev nor a Next link ... so, what happens then? Is this another special case? And is 
more special handling required? 

While the case is special, additional handling shouldn’t be necessary because— 
if the deleted item is the only remaining item in the tree—FirstLink will now be 
pointing to a nil pointer and nothing else needs to be done. In this instance, the 
special case has taken care of itself. 

The next decision is to determine if the item to be deleted, indicated by APtr, 
was connected to a Prev or Next link and this is accomplished by calling the Precede 
function with the Name fields of the current item and its root. If there is no root 
item (i.e., if the current item is the root), then the Precede function returns a fail-safe 
FALSE result and, once more, no special handling is necessary. 


if Precede( APtr*.Item*%.Data.Name, 
APtr*.Root*%.Item*.Data.Name ) then 
begin 

Beyond this point, the code becomes two symmetrical branches, each reflecting 
the other. 

Following this decision branch, the current entry was determined to be 
descended from its root entry by a Prev link so this branch begins by deciding if 
the current entry has a Next link that will require handling. 

If there is no descendant Next link, the situation is simplified and the next 
question is whether there is a descendant Prev link or is this the end of the branch. 


if APtr*.Next = nil then 


begin 
if APtr*.Prev = nil then 
APtr*® .Root’%.Prev := nit<evee 
begin 


APtr*.Root%’%.Prev 
APtr®. Prev’ Root: 


APtr®.Prev; 
APUr’ «ROOT: 
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end; 
end else 


If the current entry is the end of the branch then the Root node is set to nil and 
that’s all that needs to be done, the current entry has been cut free. The current 
entry’s Prev entry is connected back to the Root and the Root to the Prev entry. If 
the current entry did have a Next link then the situation is slightly more complex 
and begins by assigning BPtr to the Next entry, ensuring that a handle is available 
when needed. 

The next step is to decide—since it’s already known that there is a Next link—if 
a Prev link exists. 


begin 
BPtr := APtr%*.Next; 
if APtr*.Prev = nil then 
begin : 
APtr*.Root*.Prev := APtr*.Next; 
APtr>. Next* Root := APtr®. Koot; 
end else 


If there is no Prev link, then the Next link is connected back to the Root and 
that’s it—all’s well and the BPtr was unnecessary. If there is Prev link, however, 
then it takes precedence and is connected back to the Root, leaving the old Next 
link, saved as BPtr, to find its new location. 


begin 
APtr® Root’. Prey 
APtTYT*. Prev*. Root 
APtr s:= APtr*’.Prev; 
while APtr*.Next <> nil do 

APtr. 2:2 (APCR? ext: 

BPtr®, Root, 2:5: AF tr; 
APtr*.Next BRPtr; 

end; 

end; 
end else 


APtr*. Prev; 
APtr*®. Roots 


Following the rules previously described, APtr is stepped down the branch, 
always taking the Next link, until an empty Next link is found where BPtr can be 
connected. This connection can be made anywhere along the branch or, if nothing 
is found sooner, will occur at the end of the branch. 

At this point, new links have been established for any and all descendant 
elements in the tree and all that remains is to dispose of the memory allocated to 
the current item and its node pointers—which is easily accomplished: 
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Dispose( ItemPtr*.Item, Done ); 
Dispose( ItemPtr ); 
end; 

The static local pointers, APtr and BPtr, were used so that these could be 
manipulated freely without losing track of the essential pointer, ItemPtr, which is 
needed, in the final step, to call the Dispose utility. 

One feature worth comment: deletions within the binary tree tend to produce 
linear branches while new additions tend to sprout subbranches. As the tree 
evolves, assuming a balance between additions and deletions, the structure of the 
tree will tend to simplify, approaching a linear structure (as demanded by the laws 
of entropy). 

Even in a linear format, however, the binary tree tends to be faster to transmit 
than the equivalent, purely linear structure and this will remain true regardless of 
size. (Actually, binary tree efficiency increases with size compared with the equiv- 
alent linear structures.) 


Other Methods 

A variety of other methods could be created for use with the binary structure. For 
example, the Find and FindPartial methods could both be improved to meet 
probable application requirements. 

Taking the FindPartial method as a sample, an enhancement might be to include 
provisions, when a partial match is found, to inquire if this is the desired element 
or if a further search—continuing from the present, recursive location rather than 
beginning again at the root—should be executed. 

The same could be applied—though in a more limited fashion—to the Find 
method to provide for the circumstances where several entries might begin identi- 
cally: as would be the case with Jones, Bill, Jones, Sarah and Jones, John J. 

Search methods do not need to be limited specifically to the Name field of an 
entry and, with complex data fields, might well be designed to execute partial 
searches on several fields within an entry. They might also execute different 
searches on different fields within a single trip though the tree. 

For complex data, multiple binary trees can be constructed, each linking 
through a different field or different rules (or both). Figure 35-6 shows the same 
tree organization illustrated in Figure 35-3 and adds a second binary tree—using 
the same data—but linked through the Phone field instead of the Name field. The 
data entries have been replaced by integers showing the order in which each record 
was added to the tree and these are, of course, consistent for both trees. 
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Figure 35-6: Two Binary Trees 





Data linked by Name field 





As youcan see, both trees have the same root entry since the root entry is simply 
the first record read from the file and, purely by coincidence, the second and fifth 
entries have the same relationship in both trees. Beyond this, however, the two trees 
are distinctly different. 


Chapter 35: Binary Tree Objects 693 


Even if the data source is ordered for one data field, it will most certainly be 
disordered for the second and third fields. And disorder, with binary trees, is an 
advantage rather than a liability. 

When working with multiple tree indexes, however, it may help to work out 
and test the rules for each tree organization separately. Once two or more trees are 
combined in an application, complex searches can be made very quickly by com- 
paring the pointer addresses returned by separate search methods. 

Remember, even though the organization used by different tree structures will 
be different, the addresses of the data elements indicated by the separate link nodes 
will be the same; that is, assuming that both trees’ nodes are pointing to the same 
data element. 

All is not well, however, because multiple trees will also require additional 
handling in the Deleteltem method to ensure that all trees are correctly updated 
before an item is actually deleted. Since the data items do not have pointers to their 
nodes—only the nodes have pointers to the data—each tree’s nodes would need to 
be searched independently and some care taken to ensure that each tree’s node was 
indeed pointing to the same data element. 

Of course, with multiple trees, a pointer for each tree could be added to the data 
element, pointing back to the data element’s node for each separate tree. This could 
simplify several processes. There are no simple answers for multiple trees but the 
results can be very powerful and very fast, especially when large data bases and 
complex data fields are used—keep these possibilities in mind. 


Summary 


Binary tree structures are powerful and fast as well as compatible with object 
methods. 

Notice particularly that the PhonTree demo has not only created a binary tree 
organization, but provides methods by which the tree object manipulates itself, 
adding, arranging, searching and deleting data elements, even deleting the tree 
itself, all without requiring intervention by the application. 

This is the heart and soul of object-oriented programming. Once an object has 
been created and supplied with the appropriate methods, it is capable of acting by 
itself, exercising considerable powers of decision and, in general, carrying out 
complex tasks without requiring supplemental programing. 

Some of the objects demonstrated have been static objects, declared by the 
program and remaining in memory until the program exits. Others have been 
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dynamic object capable of requesting their own memory allocation when created 
and, when no longer wanted, erasing themselves and releasing the memory used 
for other tasks. Some have appeared both as static and as dynamic objects in 
different instances. 

You've seen objects as graphic control elements, not only controlling their own 
presentation, but even querying the mouse object to find out if a mouse hit has 
occurred and reacting accordingly. These are only a few of the ways in which objects 
can be created and only a few of the tasks that objects can undertake. An object can 
be virtually anything from a simple scrollbar in a graphics program to a complex 
binary tree organizing data to an entire editor utility called on by an application as 
needed and released when no longer required. 

The choices are yours: use simple objects for simple tasks or create complex 
objects for complex tasks. Virtually anything which you can program can be 
programmed as an object or using objects. The only real limits, because this is 
always true, are those of your imagination. 

So, unshackle your familiar fetters and habits and let yourself go and have fun! 


{ PhonTree.PAS } 
{ demonstrates a binary tree List } 
{ use MakeList.PAS to create data } 
{ file for use with this program } 
{Set esestsseesees seers esteseesse=eazsses=) 
uses Cft. DOs; 
type 
NodePtr = “NodeRec; 
LinkPtr = “*LinkObj; 
DataPtr = *Data0Obj; 
NodeRec = record Root, Prev, Next : NodePtr; 
Item : DataPtr; end; 
LinkObj = object 


Nodes : NodePtr; 
constructor Init; 
destructor: Bone: ovMirtuals 
procedure Add( ThisItem : DataPtr ); 
procedure DeleteItem( ItemPtr : NodePtr ); 
procedure PrintList( ItemPtr : NodePtr ); 
procedure ReadFile(€ NameFile : string ); 
function Find( RefLink : NodePtr; 

S@arenster: tat rine 2: Nodertr: 
function FindPartial(€ RefLink : NodePtr; 

Part TetStr:t string )¢ Nodertr: 
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function Precede(: Strt, Str2 : string 2: boolean; 
end; 
DataIltem = record Name : stringl40]; 
Phone : stringl141]1; end; 
DataObj = object 
Data : DatalItem; 
constructor Init(€ ThisItem : DataItem ); 
destructor Done; virtual; 
procedure Print; 
end; 
var 
LinkList ©: LINkOST: 
FirstLink ©: NodePtr; 
Mem1, Mem2 : Longint; 
Hr, Min, Sec, Hun : word; 
i: integer; 


{seeseeesesssesesessee=} 
{ Link implementation } 
{sese2aeeszscesseessees=} 

constructor LinkObj.initt; 

begin 

end; 


destructor LinkObj.Done; 
procedure DisposelItem( ItemPtr : NodePtr ); 


begin 
if ItemPtr <> NIL then 
begin 
if ItemPtr*.Prev <> NIL then 
DisposeItem( ItemPtr%’%.Prev ); 
if ItemPtr*.Next <> NIL then 
DisposeItem( ItemPtr’*.Next ); 
if ItemPtr*.Item <> NIL then 
Dispose( ItemPtr*.Item, Done ); 
Dispose( ItemPtr ); 
end; 
end; 
begin 
DisposeItem( FirstLink ); 
end; 
procedure LinkObj.Add; 
var 


NPtr : NodePtr; 


procedure BuildTree( RefLink, NewLink : NodePtr ); 
begin 
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if Precede( NewLink*.Item*.Data.Name, 
RefLink*.Item*.Data.Name ) then 


begin 
if RefLink*’.Prev = NIL then 
begin 


RefLink*.Prev 
NewLink*.Root 
end else 
BuildTree( RefLink*.Prev, NewLink ); 
end else 


NewLink; 
RetLink: 


begin 
if RefLink*.Next = NIL then 
begin 


RefLink*.Next 

NewLink*.Root 
end else 
BuildTree( RefLink*.Next, NewLink ); 


NewLink; 
RefLink; 


end; 
end; 
begin 
New( NPtr ); 
NPtr*. Root se NIL: 
NPtr* Next := NIL? 
NPtre* Prev ¢:2 NILs 


NPtr*’. Item : ThisIltem; 
1f Fireteink = NIL 
then Firstlink: = NPtr 
else BuildTree(€ FirstLink, NPtr ); 
end; 


procedure LinkObj.ReadFile; 
var 
NewItem : Dataltem; 
DataFile : file of Dataltem; 
begin 
assign( DataFile, NameFile ); 
reset( DataFile ); 
repeat 
read(€ DataFile, Newltem ); 
Add(€ New DataPtr, Init€ NewlItem ) ) ); 
unt?tl EOFC DataFile ); 
close( DataFile ); 
end; 
procedure LinkObj.PrintList; 
begin 
if ItemPtr <> NIL then 
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begin 
if LtemPtr*®,. Prev <> RIL. then 
Printldatc Per tr..P rev «23 
with ItemPtr’%.Item*% do Print; 
if ItemPtr*.Next <> NIL then 
PrintList¢ IteaPtr”. Wext (23 
end; 
end; 


procedure LinkObj.Deleteltem; 
var 
APtr, BPtr : NodePtr; 
begin 
APtr := ItemPtr; 
if APtr = FirstLink then 
if Flreti yan Prev © ee 
then FirstLink FirstLink%’%.Prev 
else FirstLink : FirstLinx®. Next > 
if Precede( APtr*.Item*%.Data.Name, 
APtr*.Root*.Item*.Data.Name ) then 


begin 
if APtr*.Next = NIL then 
begin 
if APtr*.Prev = NIL then 
APtr®. Root’. Prev s= NIL else 
begin 
APtr®. Reat*  ;Prev:-s= APtr*. Prev; 
APtr* .Prev* Root -f2:-APrtr”. Root; 
end; 
end else 
begin 


BPtr := APtr*.Next; 

if APtr*.Prev = NIL then 

begin 
APtr™. Root". Prev 
APtr*.Next%.Root 

end else 

begin 
APtr*’*.Root%’.Prev 
APtr’*.Prev%’%.Root 
APtr := APtr%.Prev; 
while APtr*.Next <> NIL do 

APtr := APtr%*.Next; 

BPtr*.Root := APtr; 
APtr*.Next := BPtr; 

end; 

end; 


APtr*. Next: 
APtr®, Root: 


APtr*. Prev; 
APtr*. Roots 


698 USING TURBO PASCAL 6.0 


end else 
begin 
if APtr*’.Prev = 
begin 
17 APtr* -Next. = 
APtr*.Root*.Next := 
begin 
APtr*.Root*%.Next 
APtr*.Next%’%.Root 
end; 
end else 
begin 
BPtr := APtr%*.Prev; 
TP LAPTr® Next = KIL 
begin 
Artr., 
APtr®’. 
end else 
begin 
APtr*.Root%’%.Next 
APtr*.Next*.Root 
APTS £2 APEr" Next: 
while APtr%*.Prev <> 
APU (3s 
BPirt ; Root. ¢s 
APtr*®.Prev := 
end; 
end; 
end; 
Dispose ( 
Dispose ( 
end; 


function LinkObj.Find; 
var 
Result NodePtr; 


function BMateh( strt, 
var 


NIL then 


Root*.Next 
Prev*.Root 


APtr; 
BPtr: 


ItemPtr*.Item, Done 


rtemPtr 2: 


Stree 


integer; 
boolean; 


ee 

Result 
begin 
Result := TRUE; 

1 32 orgt Streit cted: 2 

1 tec great: stretoa: 

To} SAS RAO Ee 

TOC ee The ae 


. 
7 

. 
7 
J; 


NIL then 


NIL else 


APtr* Next: 
APtKr® Reo Tt? 


then 


APtr%. 
APtr%. 


Prev; 
Root; 


APtr®. 
APtr®.,. 


Next; 
Root; 


NIL do 


APtr*’.Prev; 


string ): boot.esn; 
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if Result then 
Result := 
upcase(StriCj]) = upcase(Str2ljd); 
Match := Result; 
end; 


begin 
Result := NIL; 
if RefLink <> NIL then 
if Match( SearchStr, RefLink*%.Item*.Data.Name ) 
then Result := RefLink else 
if Precede( RefLink*.Item*.Data.Name, SearchStr ) 
then Result := Find( RefLink*.Next, SearchStr ) 
else Result := Find(t Reflink*®.Prev, SearchStr 2; 
Find := Result; 
end; 


function LinkObj].FindPartial; 
var 
Result : NodePtr; 


function Match( Stri, Str2 : string ): boolean; 


var 
1, | € ANEOQEer;, 
begin 
for 4 ¢= 1 te oral StritGld 2.-doe 
Stri£—i] :* upcaset *StrTeyd 3; 
for 1 22.1 toe ord( Str2cC0j ? do 
Strzfij = upcaset Str2Cid 2; 


yj ge post Strt, Stee 27 
Match +a 7 <S OF 
end; 


begin 
Result := NIL; 
if RefLink <> NIL then 
begin 
if RefLink*.Prev <> NIL then 
Result := FindPartial(RefLink*%.Prev,PartialStr ); 
if Result = NIL then 
if Match( PartialStr, RefLink*.Item*.Data.Name ) 
then Result := RefLink; 
i Result = NIL then 
if RefLink*.Next <> NIL then 
Result := FindPartial(RefLink*%.Next,PartialStr); 
end; 
FindPartial := Result; 
end; 
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function LinkObj.Precede; 


var 
: ee integer; 
begin 
1 oe onde StritCGd >): 
om. ds 
Wwhile€ upcase(Str1CjJ) = upcase(Str20Cjl]) ) 
one. 4 Tae fe? ae inet. Fis 
Precede := upcase(StriCj]) < upcase(Str20Cjjl); 
end; 
{ Data implementation } 
constructor DataObj.Init; 
begin 
Data := ThisItem; 
end; 
destructor Data0Obj.Done; 
begin 
end; 


procedure Data0Obj.Print; 
begin 
with Data do 


writeln(€ Name, Phone ); 


{ read available RAM 


end; 
{ end of Data methods } 
var 
LocPtr NodePtr; 
Locstr string: 
begin 
clreéers 
gotoxy( 4, 1 ); writeln('Name or Company'); 
gotoxy( 42, 1 ); writeln(€'Phone Number'); 
Mem1 := MemAvail; 
FITStLink: 3= NIL; 
GetTimeC Hr, Min, Sec, Hun); 


with tinkkist do 

begin 
Enits: 
ReadFile€C'PHONE.LST'); 
PrIntLiet¢t: Firestlink >; 


writeln; 


Locstr := 'Borland" : 


1 (ore@ate- eo Link tist 
{ read the data file 
{ print our the list 





LocPtr s= Find( FirstLink, 
if LocPtr <> NIL then 
begin 


writeC'Found: '); 
LoePEir™, (ter. Print: 
end else writetn( LocStr, ° 


if LocPtr = NIL then 
begin 
LocPtr := FindPartial ¢ 


1% Locher <F NGL -tAheN 
begin 
write<t* Found: *°2} 
LocPtr*. ten. Prrints 
end else writeln( LocStr, 
end; 
if LocPtr <> NIL then 
begin 
DeleteItem( LocPtr ); 
writetnt *s*=", Leettr, ” 
wry tet ne 
PrintList( 
end; 
Mem2 := 
Done; 


rirstLlink 2; 


MemAvail; 


end; 


writeln; 


writeln(¢ 


‘Available memory, 


FirstLink, 
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Locstr #2 


not founa'); 


Lots ter 2 


' not found’); 


deleted***'" ); 


{ read available RAM } 
{ dispose of list } 


T0at rece *, 


Mem1:6, ' bytes" ); 
writeln( ' : after C34et 2a: *, 
Mem2:6, ' bytes' ); 
writelnc¢ |' after disposatle.", 
MemAvail:6, ' bytes' ); 
readln; 
end. 
{sseeeseesrsssssssssese=zs=}) 
{ MakeList.PAS } 
{ creates data file for } 
{ use with PhonTree.PAS } 
feneseesrrsssressseseseses=} 


uses Crt; 


const 


FileName 
NullStr 


type 


‘PHONE.LST‘ ; 
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NameRecord = record 
Name : stringl40]; 
Phone 2 etringli473 end; 


var 
ListFile : file of NameRecord; 
FileEntry : NameRecord; 
Finish : boolean; 


function Read_Name : string; 


var 
TempStr: string; 
begin 
Tempstr s= ‘'': 


writet “tnter name: ' 22 
readln(€ TempStr ); 
Read Name := TempStr; 


end; 
function Read_Number : string; 
var 
Tenpstre strings 
begin 


TOMDSEC Pets ys 
write(€ "Enter phone number: ' ); 
readln( TempStr ); 
Read Number := TempStr; 
end; 


begin 
Cirsers 
Finish := false; 
writeln(€ ‘Enter names and phone numbers', 

" for demo program file' ); 
writetet. *Enter blank Eine to exit: * ds 
assign(€ ListFile, FileName ); 
rewrttet LietFite 
repeat 

FileEntry.Name := Read_Name + NullStr; 
FileEntry.Phone := Read Number + NullStr; 
Finish := (FileEntry.Name = NullStr); 
if not Finish then write( ListFile, FileEntry ); 
until Finish; 
close€ ListFile ): 
end. 


Part 4 


Introducing Turbo Vision 


If you have not yet upgraded Turbo Pascal 5.5 to version 6.0, this section of this 
book will not mean a great deal because you will not have access to Turbo Vision. 
However, do not permit this to disuade you from reading further: Turbo Vision is 
too important to simply ignore. 


The Importance of Turbo Vision 


Earlier, | have stressed the importance of reusability—of developing descendant 
object types to reuse previously developed code instead of continually reinventing 
the wheel. I’ve also demonstrated the development of a number of object types with 
general purpose applicability; the mouse object, buttons, scroll bars and binary- 
trees. 

With the release of Turbo Pascal 6.0, Borland has also provided a series of base 
object types gathered together under the name Turbo Vision. These also may be 
used as is or indirectly as ancestor types for the development of your own object 
types. 

In Turbo Pascal 6.0, the new integrated development environment—now titled 
the Programmer’s Platform—was written using the Turbo Vision toolbox. Accord- 
ing to reports, this task was accomplished with a fraction of the effort that would 
have been required to create it from scratch. Object reusability saves time! 

Turbo Vision saves you the time of developing a number of useful—and 
reusable—basic object types. 
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The Turbo Vision Toolbox 


The Turbo Vision toolbox is a framework of objects that can be used to construct 
and operate event-driven windowing application and provides support for: 


« multiple, resizable overlapping windows 

» pull-down menus 

« dialog boxes 

« input boxes 

# mouse support 

= mouse interactive buttons, radio buttons, check boxes and scroll bars 
« standardized keystroke and mouse event handling 


Perhaps most important, however, is the fact that all of these object-oriented 
features are not only user-interactive but are mutually interactive as well. In this 
fashion, a text window can be created with horizontal and vertical scrollbars and 
repositioning or resizing the window—using either the mouse or the cursor keys— 
also adjusts the scroll bars. 

Granted, any application could create separate objects to accomplish these tasks 
and some aspects of mutually interactive objects have already been demonstrated 
in earlier examples, but these examples required a minimal amount of attention 
within the main program. 

Ideally, all of these object interactions should be part of the object design and, 
thus, invisible to the applications using the objects. Turbo Vision has been designed 
to accomplish just this. 

To handle such intra-object interactions, and to provide communications to and 
from the application, a new concept known as event-driven programming lies at the 
heart of the Turbo Vision package. 


Event-Driven Programming 


In actual fact, event-driven programming is not completely new and has been used 
in several specialized environments including Microsoft Windows as well as the 
over-publicized OS/2 where virtually nothing could be accomplished except by 
passing an event message. 

In SerlTst2.PAS, in Chapter 34, the button and scroll bar objects operated by 
querying the mouse object directly, asking if mouse button events—mouse clicks— 
had occurred and, if so, what the mouse coordinates were when the event occured. 
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When one of these objects determined that a mouse event had occurred, the object 
updated its own status and screen display before reporting a message—or an 
event—back to the calling application. 

But this was a very simple example and qualifies as event-driven programming 
in only the broadest possible sense because here direct interrogation was used to 
process mouse events. While this type of handling does work, it is also limited in 
application and still requires intervention by the main application. 

Event-driven programming is characterized by event messages that are dis- 
patched by a central event-handling mechanism. In this fashion, the main applica- 
tion is relieved of the task of handling input events and calling the various 
subroutines. Instead, the application using an event-driven object group operates 
by waiting for the event-handling mechanism to pass event messages for handling 
and, at the same time, many other object processes may be handling their own tasks 
quite invisibly without the attention of the main program. 


Conveniences and Constraints 


While event-driven object programming provides new capabilities and new con- 
veniences, it also imposes constraints on the programmer. For example, instead of 
an application polling the mouse for a mouse click and then telling the button or 
scroll bar how to react, the buttons and scroll bars report events to the application 
... and this is message or event-driven programming. 

In event-driven programming, objects become effectively autonomous, taking 
care of their own requirements and reporting messages to the calling application 
allowing it to respond as appropriate. But without the application having to 
concern itself with the details of how the objects function. 

Before event-driven programs can work effectively, however, the programmer 
faces a few limitations restricting the free and easy, test and revise, try and patch 
programming which so often characterizes application development. 

Because event-driven programing depends on objects that can act autono- 
mously, these objects must be well designed with full consideration for both the 
tasks which each object must accomplish and for the events which the object will 
report to the application. 

Applications using autonomous objects also face certain constraints and must 
act through the objects—by passing messages or parameters to the object and 
calling on object methods to accomplish tasks rather than operating directly and 
independently and bypassing the object’s methods. For example, once you have 
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created an object-window, anything you want written to this window must be 
written by the object, not written directly to the screen by the application because 
only the window object knows where it is and where its borders are and if it is 
hidden by some other window. 

How these constraints operate and how to take advantage of the corresponding 
conveniences will be the main topics of the next chapters. 

I hope that none of this has scared you, because the conveniences of event- 
driven programming far out weigh the constraints. As I've said before, objects are 
not only useful, they are also fun. 

So, let the fun begin ... 


Chapter 36 


Using Turbo Vision 


Ideally, programming should be fun and it is—most of the time. But it also seems 
as though we spend a lot of time either reinventing the wheel or searching though 
our parts bins for the tools and components to put one together and then hoping 
that all the parts fit or having to modify the ones that don’t. This is particularly 
annoying when the parts we’re spending most of our time constructing have very 
little connection with the problem we’re actually interested in solving. 

This is the strength of object-oriented programming: the convenience of reusing 
existing support structures and freeing us to tackle the meat of the application 
instead of repeatedly rebuilding the bones and hide to hold everything together. 

However, even the possibility of objects, introduced by Turbo Pascal 5.5, still 
left the onus of creating the basic object types on the programmer—until Turbo 
Vision appeared. 

Now, with Turbo Vision, we have the object framework for event-driven 
window-based application supporting buttons, check-boxes, error reporting, field 
editing, input dialogs, help features, menus and mouse handling. 

But Turbo Vision is not a replacement for programming because it serves as a 
framework rather than an application and an application is whatever the program- 
mer creates using the framework. 
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Creating a Turbo Vision Application 


One characteristic of object programming is that the main body of the source code 
can be very brief, often consisting of little more than a series of commands to set 
up (initialize) objects, then put the objects into action and, last, cleans up afterwards. 
In most of the examples in this section of the book, this rule will be carried to an 
extreme with the body of the examples consisting of three lines, thus: 


begin 
ThisApp. Init; { initialize 
ThisApp.Run; { execute 
ThisApp.Done; { clean up and 
end. 


Not very complicated, is it? 

This should also offer an indication of where the differences begin in event- 
driven programming. Previously, applications began by calling on procedures to 
accomplish various tasks, passing control down through chains of procedures and 
subprocedures until the task is completed. 

With event-driven programming, however, the ideal is for an application to call 
a single object, and then let the object take over until it’s time to clean up. Granted, 
there is still a far gap between the ideal and the real but, in demonstrating Turbo 
Vision, we'll emulate the ideal as much as possible. 


A Different Approach 


Obviously, attempting to meet the ideal of object programming requires a different 
approach than usual to create the source code for the application. 

At some time or another, you’ve probably used program libraries as extensions 
to Turbo Pascal procedure and function libraries. And, depending on the library, 
you've found useful features for creating menus and windows or data structures 
and entry fields or something useful in some degree or another. I admit I have also 
provided utilities such as graphics button objects, mouse objects and linked lists 
for use in your applications. 

But, when any of these have failed to supply precisely the features or functions 
needed for your applications, your solution has probably been to rewrite the source 
code, adapting the library to satisfy the objective at hand. 

This, however, is where the differences between conventional and object pro- 
gramming diverge acutely. 


exit 
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Modifying a program library, as source code, is fine for tailoring functions and 
procedures to supply precisely those features desired. But, this is also a fine way to 
introduce the unexpected (i.e., bugs). 

With object programming libraries, a different approach to revision becomes 
possible. With objects, the source code itself does not need revision because objects 
can be extended by deriving new—descendant—object types incorporating any 
additional features desired. This may include overriding ancestor object methods. 


Toolboxes vs. Frameworks 


A second major difference, in the case of Turbo Vision, is the difference between a 
package of separate tools and an integrated, multi-functional system. The capabil- 
ities provided by Turbo Vision are designed not for individual operation but to 
work as part of a single integrated framework. 

Rather than incorporating bits and pieces from Turbo Vision into your applica- 
tion, the reverse approach is to incorporate your application within Turbo Vision’s 
framework (i.e., using Turbo Vision as a skeleton to hold the meat of your applica- 
tion). We'll begin by looking at a very simple application using Turbo Vision and 
then build more complex versions from there. 

The listing for TVDemo1.PAS shows a minimalist application which, in actual 
fact, does almost nothing. Figure 36-1 shows the display produced by TV- 
Demo1.PAS with the blank center of the screen omitted. 

This display should look familiar since this is the display used by both Turbo 
Pascal and Turbo C programmer’s platforms, but notice the menu line (top of 
screen) is empty while the prompt line (bottom of screen) displays a single, default 
option: Alt-X Exit. 

Both the screen and exit option are built-in defaults used by Turbo Vision when 
no other provisions have been specified. The Alt-X quit option will be retained, by 
specific inclusion, in subsequent examples but could be reassigned to any desired 
key event such as Alt-Q, Ctrl-Q or Ctrl-X. 

In this version, as can be seen in the source code following, all mechanisms are 
effectively invisible, but will become more visible in subsequent examples. 

For the present, TVDemo1 begins with a uses statement referencing the App 
unit which will supply the TApplication object definition needed here. 


uses App; 


Next, a local object type, AppObj, is declared as a descendant of TApplication. 
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type 
AppObj = object( TApplication ) end; 
However, TApplication is only the end descendent of a heirarchy beginning as: 
TObject — TView — TGroup — TProgram — TApplication and, as such, has quite 
a complex of resources available (see Figure 36-4 for a complete object heirarchy). 


var 
ThisApp: AppObj; 

Last, a specific object instance, ThisApp, is declared for use by the program. 
All that remains is the main begin...end block presented earlier. 

A total of 10 lines of code compile a simple object-oriented application that 
creates a background display, presents an exit prompt and responds to either a 
keyboard entry or to a mouse click on the prompt. The fact that it is not particularly 
useful is immaterial at this point because additional features will be added in 
subsequent examples. 

The primary point here is that all of this is accomplished by a single framework, 
while previous tool-box accessories would have required combining dozens or 
even hundreds of separate utilities to produce even this minimalist result. 


Figure 36-1: TVDemo1.PAS—A Minimal Turbo Vision Application 





Adding New Features 


Before a viable application can be produced, a lot more will be required than a 
simple Exit prompt. Therefore, TVDemo2 will begin the process by adding addi- 
tional prompts in the status line. 

Since the default status line in the TApplication object is created by the Init- 
StatusLine method, the local object type, AppObj, begins by declaring a new 
InitStatusLine method to overwrite the ancestoral method. 


type 
AppObj = object( TApplication ) 
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procedure InitStatusLine; virtual; 
end; 


Because the ancestoral method is virtual, the redeclaration of this method must 
also be virtual (and would be if this specification were omitted, but it is included 
here as a reminder). 

However, it is the implementation for the InitStatusLine method that does the 
actual work and begins by declaring a local variable: 


procedure AppObj.InitStatusLine; 
var 
Rect: TReect; 


TRect is a predefined structure containing two pairs of coordinates, A and B, 
which correspond to the corners of a rectangle. A and B each contain X and Y 
positions. Thus Rect.A.X sets the left column position of a rectangle. 
begin 


GetExtent( Rect ); 
Rect, ,Avw¥Y I Reet.b.¥ = 13 


The GetExtent method belongs to TView which is an ancestor of AppObj and 
returns the entire size of the view or screen as 0, 0, 80, 25. Since these coordinates 
would result in the status line being overwritten by other parts of the screen, a slight 
change is required to insure that the new status line is positioned appropriately at 
the bottom of the screen. 

Instead of simply setting Rect.A.Y equal to 24, this version makes provisions 
for 43 or 50 line screens as well as 25 line screens. 

Next, a new status line initiation is defined. StatusLine and MenuBar initializa- 
tion format are a bit different than familiar procedures and methods and will 
require some explanation in a moment. 

First, however, the elements StatusLine, PStatusLine, NewStatusDef and New- 
StatusLine are all predefined in the modules used by this example. StatusLine is a 
global variable storing a pointer of type PStatusLine to the new status line infor- 
mation. The NewStatusDef method contains nested status line elements and is 
initialized with minimum and maximum arguments (0 and $FFFF) setting limits 
on the range of help contexts (will be used later). 


StatusLine := 
new 
( PStatusLine, 
Init 
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( Rect, 
NewStatusDef 
( Oo STEFF, 


Note: the dots in the source code example here and following have been added 
to simplify following the alignment of nested parentheses and to make the structure 
of a relatively complex nested statement simpler to follow. Normally, such extreme 
indentation would not be necessary or appropriate. 

The first status line entry is declared by NewStatusKey with a parameter list 
beginning with the status line message. The portion of the string enclosed by tildes 
(~) will be highlighted (red on color systems) while the balance of the string will be 
in black. The kbAItX parameter associates the Alt-X key with this message and with 
the screen position of the message. The cmQuit parameter is the event message that 
will be issued when the Alt-X key is pressed or if the status line message is clicked 
with the mouse. cmQuit is predefined as 1. Typically user-defined event messages 
should begin at 100 to prevent conflicts with predefined messages. 


NewStatusKey 
Te K ee eee 
kbALtX, cmQuit, 

While the Alt-X key was previously defined by default, the default method is 
being overwritten and must be reimplemented here or else there would be no way 
to exit from this program (except by a reset). 

Next, a second status line message is nested within the definition of the first 
status line message, associating the message Alt-F3 Close, the Alt-F3 key and the 
cmError event message. 


NewStatusKey 

Vor aero ° OlOges, 
kKbALtFS, cmError, 
nil 

) 

At the moment, the prompt Close is inapplicable; therefore, the cmError event 
message has been assigned but a different event message will be assigned later. 
cmError is provided to represent unimplemented commands and is useful during 
testing and development without having to contend with spurious event messages 
during this process. 

In this example, only two status line prompts are being implemented so this 
nesting is terminated by a nil entry. If additional status line prompts were desired, 
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another NewStatusKey would appear here with its own string, message and event 
parameters. 


Aother nil entry ends the NewStatusDef definitions followed by closing paren- 


theses to complete the nesting. 
Figure 36-2 shows the display produced by TVDemo2.PAS. 


Figure 36-2: TVDemo2.PAS Display 





Adding Menus 


Now that a beginning status line has been set up, the next task is to create a menu 
bar at the top of the screen. A default menu bar has been present in the previous 
examples—appearing as a solid blank at the top of the screen—but it would be 
more useful with some menu selections displayed and, of course, a series of 
pull-down menus for the menu items. 

At the same time, a third and fourth status line message will be assigned but, 
as you will see in a moment, one of these will be invisible. 

But, before revising the menu bar display, the existing InitMenuBar method 
must be redefined, thus: 
type 

AppObj = object( TApplication ) 

procedure InitStatusLine; virtual; 


procedure InitMenuBar; virtual; 
end; 


As with InitStatusLine, InitMenuBar is already a virtual method but the 
ancestoral version of this method will now be reimplemented with new provisions. 
As with InitStatusLine, the source code has been indented to show the nested 
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structure of the declaration and dots have been added to clarify the organization 
of the nested parentheses. 

procedure AppObj.InitMenuBar; 

var 

Rect:  TRects 
begin 

GetExtent( Rect ); 

Rect 8.7% s#i Rect way Yor ot: 

As with the InitStatusLine method, the Rect coordinates need to be set to 
confine the menu bar display to the appropriate area of the screen. This time, 
however, the second coordinate pair is set one line down from the first. 

MenuBar is a pointer of type PMenuBar, both of which are defined in the object 
units. 


MenuBar !:= 


new 

( PMenuBar, 
Init 
( Rect, 


NewMenu 


First, we create a new menu bar by calling the NewMenu method and instruct- 
ing it to call the NewSubMenu method to create a menu entry titled ‘File’ with an 
associated submenu. 

€ NewSubMenu 
ee fe 
hcNoContext, 

And NewMenu is called again to create the submenu with Newltem called to 
create the first entry in this submenu with the prompt ‘Open’ and the key entry 
‘F3’—both of which are included in the display but with the second item flush right. 
If no function key is associated with an item, a blank or null entry can be used for 
this field but, in this case, the key event code kbF3 is also assigned for this menu 
item. The highlighted letter is also an active selector—by default—but only after 
the menu has been pulled down or, for the menu bar, when control has been shifted 
to the menu bar (see the F10 entry in the status line). 

Since this menu entry will not have any function at present, the cmError event 
message is assigned and the flag hcNoContext used to indicate that no help text is 
currently associated with this entry. 


NewMenu 
( Newltem 
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( '*0"pen', 'F3", kbFS, 
cmError, hcNoContext, 
And asecond menu entry appears as ‘New’ with it’s own hot-key and the same 
event and help items. 
NewItem 
C ee OM TFS KDFS, 
. > i : : i ; cmError, hcNoContext, 
NewLine 
The NewLine method is called at this point to separate the next item in the 
menu by a horizontal bar from the previous items. 
And the last entry for this menu is defined associating the prompts ‘Exit’ and 
‘Alt-X’ with the Alt-X key and the cmQuit event message. 
eg | aS GR Be bre aes Te eae 
. . . ‘ : : . pO er Sats TAL EHR? 5 KOAL TA, 
. i , . . ; 6 : : cmQuit, hcNoContext, 
ee es ee Cee ae” ee 2 
cab Soe we Lee eee Bey 
Since this same assignment will be repeated in the status line definition, this 
may seem redundant but it is not entirely. While the event message cmQuit and the 
Alt-X key do receive duplicate associations, this entry also associates the pull-down 
menu item and the event (action) message while the later status line entry is needed 
to associate the same event message with the status line entry ... so that either can 
be selected using the hot key, mouse click or, for the menu item, by highlighting 
and pressing return. 
Last, a second submenu is declared with the menu bar heading ‘Window’ and 
two menu entries. 
- «s « « NewSubMenu 
‘ ‘ ; P ( '~W~indow', hcNoContext, 
. : . . . NewMenu 
ee ee ee ee ee es 
a ee wh og Eee eth “RS KTR > 
3 : ‘ é ‘ ‘ ‘ cmError, hcNoContext, 
. . . ‘ : . - NewlItem 
. ; i ‘ ‘ ‘ i ( ‘7 "gonm'’ > “FS*, KEFS,; 
P , . . . ‘ ‘ , cmError, hcNoContext, 
a ee at oe eee eee ee ee 


5 ‘ . ‘ . ) ) 2 
‘ ‘ ‘ - nil 


end; 
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Again, all of these menu items, except for the ‘Exit’ item, are given the cmError 
and hcNoContext message elements until such time as other provisions are needed. 


Figure 36-3: TVDemo3.PAS Display (composite) 





Revising the Status Line 


The status line has also been revised with two new entries but the first of these is 
slightly different from the entries shown previously. 
- « NewStatusDef 
‘ Maine See trae Ae oh Oe 
a ; ; NewStatusKey 
oe et eee OS ROE Gy | OR | 

Since no prompt was assigned, this is an invisible entry but still serves a valid 
purpose in assigning the event message cmMenu to the F10 key, which means that 
pressing the F10 key will make the menu bar active, highlighting the first item on 
the menu bar. 


‘ ‘ ‘ P NewStatusKey 
‘ a ‘ : ( WSR ERS 
‘ ; ; f : kbALtX, cmQuit, 


The ‘Alt-X Exit’ item repeats the kbAlItX and cmQuit assigments which were 
made earlier in a pull-down menu item ... except that this entry also associates the 
event message with the status line prompt such that a mouse click on the entry 
sends the event message. And one more item has been added to the status line as: 
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NewStatusKey 
: ( me" F4a°”—6CUNOW', 
» « KBPS, CMERFOr, 

TVDemo3 produces the display shown in Figure 36-3 with two pull-down 
menus, the second of which has been superimposed in a composite illustration at 
an offset. Normally, two menus would not appear on screen simultaneously. 

Figure 36-4 shows the complete object hierarchy with 42 different object types. 


Figure 36-4: A Heirarchy Of Objects 


TResourceCollection 
TCollection — TSortedCollection aa 


TResourceFile 


TString Collection 


TDosStreaam — TBufStream 


TStream ai 
TEmsStream 


TString List 
TStrListMaker 
TBackground 
TObject TButton 
TCheckBoxes 
TCluster = 
TRadioButtons 
TFrame 
TDeskTop 
TGroup TProgram -— TApplication 
TDialog 
TWindow a 
THistory THistoryWindow 
TInputLine 
TView TListBox 
TListViewer ai 
THistory Viewer 
TMenuBar 
TMenu View ai 
TMenu Box 


TScroller — TTextDevice — TTerminal 


TScrollBar 


TLabel 
TStaticText a 
TParamText 


TStatusLine 
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{SSHSSSsSeesseesesSsseesrsessertsaeeasestestaaseesressss} 
{ TVDemo1.PAS } 
{ Turbo Pascal 6.0 == Turbo Vision Example } 
(SRSS SSeS SRESSeseseeer esses Sertertesteseeaszssezes=s} 
uses App; { TApplication object type 
type 
AppObj = object( TApplication ) end; { local object type 
var 
ThisApp: AppObj; { object instance 
begin 
THTSADS nit; { initialize 
ThisApp.Run; { execute 
ThisApp.Done; { clean up and exit 
end. 
(SSS SSS SSSSSSSSSBSSSSSSsTSssesseessssesessezseass=e} 
{ TVDemo02.PAS } 
{ Turbo Pascal 6.0 == Turbo Vision Example } 
(SSSSSSSSSeseeresSesse see tseseseseesesesssesse=ss=} 


uses App, { TApplication object type 
Drivers, { keyboard driver 

{ 

{ 


Menus, PStatusLine 
Objects; TRect object type 
type 
AppObj = object( TApplication ) 
procedure InitStatusLine; virtual; { redeclaration 
end; 


{ method implementation } 


procedure AppObj.InitStatusLine; 
var 
Rect: TRect>; 
begin 
GetExtent( Rect ); 
ROCTLACN 36 Rect. 8.7% = 13 
StatusLine := 


new 

C PStatusLine, 
Init 
( Rect, 


NewStatusDef 


yw 


ee ee 
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oe! Pe oe ee { NewStatusDef } 
NewStatusKey 
( ee REM DERE, 
kbALtX, cmQuit, 
{ because default InitStatusLine has } 
{ been overwritten, AlLt-X must be } 
{ redefined to return cmQuit message } 
NewStatusKey 
( PU ALT= FS" 6UInactive't, 
kbALtF3, cmClose, 


{ second function key is defined } 
{ for menu but inactive here, thus } 
{ ALt-F3 returns cmClose message } 
; nil { nil entry ends menu chain } 
) y Be 
‘ nil 
) ) 3 
end; 
{ methods end. } 
var 
ThisApp: AppObj; 
begin 
ThisApp. I nite { initialize } 
ThisApp.Run; { execute } 
ThisApp.Done; { and clean up } 
end. 
{Sees Sess Sesreesr ets SeSsSSerSSeesessetessseresess=s=so==} 
{ TVDemo03.PAS ; 
{ Turbo Pascal 6.0 == Turbo Vision Example } 
{See SESS eSersersceessssesseseaezresstee=sensesse=ses=} 
uses App, { TApplication object } 
Drivers, { keyboard events } 
Menus, { PStatusLine } 
Objects, {C TRect object type } 
Views; { hcNoContext, etc } 
const 
cmFileOpen = 100; { command message _ } 
cmNewWin = 101; { command message } 


type 
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AppObj = object( TApplication ) 


procedure InitStatusLine; virtual; { redeclaration } 
procedure InitMenuBar; virtual; { redeclaration } 
end; 


{ method implementation } 


procedure AppObj.InitMenuBar; 
var 
Rect: TRect; 
begin 
GetExtent( Rect ); 
RECT sR. te Rect va. YY Ts 
MenuBar := 


new 
( PMenuBar, 
Init 
( Rect, 
NewMenu 
( NewSubMenu 
( . FF Le 
hcNoContext, { constant for no help text } 
NewMenu 


( Newltem 
( Te BON a erst Bers. 

cmFileOpen, hcNoContext, 

NewItem 

( TN ewe TFA: KDR, 
cmNewWin, hcNoContext, 
NewLine 
( Newltem 

Pee ea eg A ee AE Bie 
cmQuit, hcNoContext, 


‘ ; : ‘ : nil 
) ) ) ) ae 
NewSubMenu 
( '""W° indow', hcNoContext, 
NewMenu 
( NewIltem 
( CORT oo FG" OC RBES. 
cmNext, hcNoContext, 
NewItem 


( ep OOM. 3 ORS 4 REPS, 
cmZoom, hcNoContext, 
‘ ‘ nil 

) ) oS 
nil 
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) ) ) ) 5 
end; 


procedure AppObj.InitStatusLine; 
var 
Rect: TRect; 
begin 
GetExtent( Rect ); 
Rect. A.¥ +2 Rect .8.Y¥ = 7; 
StatusLine := 


new 
( PStatusLine, 
Init 
( Rect, 
NewStatusDef 
C @,. SFE, 
NewStatusKey 
( ‘') kbF10, cmMenu, 
{ hotkey assignment without prompt } 
NewStatusKey 
( TAR Exttt, 
kKbAEtTX, .eme@uit, 
NewStatusKey 
( or Fe New’, 
kbF4, cmNewWin, 
NewStatusKey 
( TWALt=F3S"” Inactive, 
kbALtF3, cmClose, 
; : ; nil 
) ) ) D 
: nil 
) ) i's 
end; 
{ methods end } 
var 


ThisApp: AppObj; 


begin 
ThisApp.Init; 
ThisApp.Run; 
ThisApp.Done; 
end. 
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Chapter 37 


More Turbo Vision 


Because an entire volume could easily be devoted to Turbo Vision (Borland’s own 
Turbo Vision Guide runs over 400 pages), space and size limitations preclude 
providing comprehensive coverage for the Turbo Vision object library. Thus, only 
an introductory treatment of the subject is provided here and you are referred to 
the Turbo Vision Guide and the example programs distributed with Turbo Pascal 6.0 
for further information. 

Still, before leaving this subject, there are a few more features that deserve 
demonstration. In Chapter 36, Turbo Vision was used to create a desktop display 
with pull-down menus as TVDemo01.PAS, TVDemo02.PAS and TVDemo03.PAS, 
demonstrating how menu structures were created. In this chapter, TVDemo04.PAS 
adds functions that are called by these menus with a dialog box selecting the 
foreground and a background colors used by other windows to display the pro- 
gram source code—a self-referential demonstration. 

Figure 37-1 shows two double-paned windows and the color selection dialog 
box with both checkbox (left) and radiobutton (right) selections, as well as a text 
input box which provides the window captions. 

The principal features here are the checkbox selections and the radiobutton 
selections. Using the checkbox selections, all, two, one or none of the boxes can be 
checked to set the foreground color. In this instance, the checkboxes select the three 
primary colors (Light Red, Light Blue, Light Green) and, according to the selection, 
these are summed together to provide a range of eight foreground colors (White, 
Yellow, LightMagenta, LightRed, LightCyan, LightGreen, LightBlue and Dark- 


ti 
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Gray). This color summation is not automatic, but is handled within an object 
method. 


Figure 37-1: Displaying a Text File with Color Selection 











second Window 2 


He | ‘Turbo Pascal 6.0 rE: 

ee ae |i 
-s App, {|uses App, 
Crt, | Crt, 
Dialogs, | Dialog 
Text Window 1 =e 


{; 
TUDe | ¢ 
Turbo Pascal 6.4 { 


Turbo Pas¢ 


ses App, {luses App, 
Crt, Crt, 
Dialogs, Dialogs, 
Dos, Dos, 
Drivers, Drivers, 





at 





The radiobutton selections (right) also choose from three colors (Dark Blue, 
Dark Green and Dark Red), but only one color can be selected from this list at any 
time. Of course, one color is always selected. If a black background is desired, it 
must be explicitly provided as a selection. At the same time, provisions are neces- 
sary elsewhere to map the radiobutton selection to a color selection. 

The third dialog item is the Window Caption where a new window title can be 
entered. In this example, the input box field is limited to 20 characters and the input 
window provides ample space for entry. In other cases, a longer entry field may be 
desired without increasing the size of the input window but the dialog entry object 
provides scrolling within the input window and adds a / symbol at the right 
whenever a string entry exceeds the displayed size. 

As with all Turbo Vision objects, the mouse can be used to select options by 
clicking on the desired item. Alternatively, either group or the input box can be 
selected by clicking on the caption and then using the arrow (cursor) keys for 
selection. 
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If you do not have a mouse, selections can be made from the checkbox and 
radiobutton lists by tabbing through the dialog items and by using the cursor keys 
to highlight selections which are toggled by pressing the spacebar. In the case of 
the checkbox and radiobutton groups, the group title is highlighted and the cursor 
keys can be used to step through the list, highlighting individual items for selection. 

After new color and title selections have been made, all subsequent F4 View 
operations will use the new settings but existing view windows will not be affected. 


A Dialog Box Data Record 


The first step in creating a dialog box is to define the type of information that will 
be retrieved from the dialog. In the TVDemo05.PAS example, three pieces of 
information are desired: the settings from a checkbox group, the settings from a 
radiobutton group and a string containing the window title. 

However, these elements are not available individually but must be retrieved 
using a record structure, which is defined as: 
type 

WinDialogData = record 
CheckBoxData : word; 
RadButtonData : word; 
WindTitle =: stringl20]; 
end; 

Checkboxes are limited to a maximum cluster size of 16 and the checkbox state 
information is bit-mapped to a 16-bit word with the first checkbox in the list 
corresponding to the least-significant-bit (bit-0). 

For radiobutton groups, a different set of restrictions apply. First, a radiobutton 
cluster may contain as many as 65,536 buttons but, since only one radiobutton in a 
cluster can be active at any time, a value of zero is returned for the first button in 
the cluster, 1 for the second, 2 for the third, etc. Again, an unsigned 16-bit word 
value is sufficient to return the group button state information. 

For the input line field, a simple string is all that is required, in this case, with 
a length of 20 characters. The Ok and Cancel buttons appearing at the bottom of 
the dialog box do not require any special provisions. Also, a static instance of the 
WinDialogData structure is declared as: 


var 
DiagData : WinDialogData; 
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Creating the Dialog Box 


The preceding data structure simply provides a place to keep the dialog data but 
it is the ApplObj.SetColors method that defines the dialog box with the checkbox, 
radiobutton and input line clusters. 

The ApplObj.SetColors method begins by defining three local variables as: 


var 
PtrView : PView; 
Dialog : PtrDialog; 
Rec : TRect; 


Rec is a local, static instance of the TRect object type and is called via the Assign 
method to set the initial size for a rectangular window. 


begin 
Rec  ASsiant 20, 6, 60, 18 2% { ref TRect.Assign } 
Dialog := 
New( PtrDialog, Init( Rec, "Color Settings Demo' ) ); 


Next, Rec is initialized as a dialog display with the caption shown while Dialog 
provides a pointer to the dialog display object. Notice that this dialog box is being 
dynamically allocated and it is not a static object instance. Therefore, before the 
SetColors method ends, the dynamic object instance will be released from memory. 

So far, however, only the dialog box outline and caption have been created and 
additional provisions are need to assign selection elements. 

The first step, rather than having to reference each element of the dialog display 
using the Dialog pointer, is to enclose subsequent statements in a with..do block. 


with Dialog%* do 
begin 


The first dialog element created begins with another Rec.Assign statement that 
establishes space for a checkbox list. 


ROC ASS TON: 25: 24. 39°6. 23 
PtrView := 
New(€ PCheckBoxes, 
Init( Rec, 
NewSItem( ‘Light “~B”lue', 
NewSItem( ‘Light “G”reen', 
NewSItem(€ ‘Light “R°ed', 
NITES obey 
) be 
Insert( PtrView ); 
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Next, a new Rec object instance is created as a checkbox display with three 
elements defined. The tildes (~) surround the label elements which will both be 
highlighted and will be the hotkeys for each item. 

Last, the dialog element indicated by PtrView is inserted into the Dialog object, 
transfering display control to this object. 

The PCheckBoxes pointer is defined in the Dialogs.TPU unit as are the PRadio- 
Buttons and PInputLine pointers used subsequently. 


Labeling a Cluster 


Simply providing a cluster of checkboxes or radiobuttons is not always enough and 
it often helps, as in this instance, to provide a label indicating what the control 
cluster is designed for. 

Again, a rectangular area is defined by calling Rec.Assign: 


Rec.Asaitan’. te Ze Tw Bo ae 
Insert (¢ 
New(€ PLabel, 
Init( Rec, 'Foreground Colors', PtrView ) ) ); 


The PLabel reference is used with the Insert method, indicating that this display 
is a label. However, where the earlier code creating the checkbox items ended with 
the nil pointer reference, this Init statement is called with PtrView. 

Refering to the two preceding code samples, notice first that PtrView assume 
an address of the checkbox cluster in the first code block before the address is passed 
to the Insert method. In the second code block, this same address is used in the 
PLabel assignment to associate the label with the checkbox cluster. 

In this fashion, clicking on any of the checkboxes will highlight the cluster label 
or clicking on the label will select the checkbox cluster. 

Next, the PtrView variable is used again to create a cluster of radiobuttons with 
a second label. 


Rec. Assitan( 225 3% See (6 Fs 
PtrView := 
New(€ PRadioButtons, 
TATtC ROC, 
NewSIltem( ‘Dark Bl”u'e', 
NewSItem( 'Dark Gr°e’en', 
NewSItem( 'Dark Re'd'', 
| is ane ) ) 
) 2 
Insert( PtrView ); 


728 USING TURBO PASCAL 6.0 
bbe asa 2 es ald bia elt ih ae Ce OCT BALL STD tS SO Cn OE eh EE TO 


ROC ASBTONE S45) 25: 36,35) 3 
Insert ( 
New( PLabel, 
Init€ Rec, ‘Background Color', PtrView ) ) je 
Note, however, that the two clusters are not associated with each other, only 
with their respective labels. 


The Input Line Box 


The input line object is the third element in the dialog and, like the preceding 
elements, begins by assigning an area. 


Rec. AS&tane; 18, 0%,  S38.:...8'.)% 
PtrView := New( PInputLine, 
INT tt: Ree, 
sizeof(€ DiagData.WindTitle ) ) ); 
Insert( PtrView ); 


The TInputLine.Init method, referenced by PInputLine, requires a maximum 
length specification which, in this example, is supplied by the sizeof function. 

A note of caution here: using a constant specification for the length parameter, 
as shown in some examples, can result in an error if the parameter and the field 
size do not match. For example, revising the size of the data field without changing 
the constant specification can result in a variety of program errors or hangups. 
Using the sizeof function is much safer. 

As before, a label field is associated with the input line. 

ROC CASSIS Ty Ute Sy eS 
Insert (¢ 
New( PLabel, 
Init(€ Rec, ‘Window Caption:', PtrView ) ) b Re. 

Last, two buttons are created to complete the dialog box, an Ok button which 
is the equivalent of the Enter key and a Cancel button which corresponds to the 
Escape key. 

Rec.Assign( ip Sp ea 
Insert 
New PButton, 
ATT Rec, ° OKs, CmORy Btbeteutt()-2 °°): 
Rec. Ags ight 28, 9, 363391) % 
Insert (¢ 
New(€ PButton, 


Init€ Rec, ‘Cancel’, cmCancel, bfNormal ) ) )5 
end; 
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This completes the display provisions for the dialog box though there are still 
a couple of tasks remaining before the dialog box is anything except a series of 
display specifications. 

The first task is to assign default values to the dialog box. 


Dialog*.SetData( DiagData ); 


The SetData method transfers whatever information is presently contained in 
the static record variable DiagData. 

When the SetColors method is called initally, of course, this information would 
be either nulls or some random data remaining from another application or 
operation except that explicit default settings were made in the main body of the 
code as: 


with DiagData do 
begin 


CheckBoxData = $07; { $01 + $02 + $04 = 0000 0111 } 
RadButtonData := $01; { sets Dark Green radiobutton } 
WindTitle := ‘Text Window’, 


end; 


On any call to SetColors after the first call, the DiagData record will simply 
reinitialize the dialog box with the values previously set. 

Next, since none of the preceding code actually writes anything to the screen, 
the DeskTop’.ExecView method is called, passing the Dialog pointer to DeskTop 
to handle the actual execution of the dialog box. When finished, DeskTop returns 
a message to the calling process. 


if DeskTop*.ExecView( Dialog ) <> cmCancel then 
Dialog*.GetData( DiagData ); 


If the return message is not cmCancel, then GetData is called to copy the new 
dialog settings—the checkbox settings, the radiobutton setting and the caption 
string—into the DiagData record structure. 

Finally, dispose is called to deallocate the memory used by the dialog object— 
another reason why the data settings must be reinitialized each time the dialog is 
called and why the settings must be retrieved before the object instance is released. 


Dispose( Dialog, Done ); 
end; 
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Calling the SetColors Method 


The SetColors object method is called, of course, by the event handler, Appl- 
Obj.HandleEvent, in response to the cmSetColors message issued by the Window 
/ Colors menu item. 


procedure ApplObj.HandleEvent( var Event: TEvent ); 
begin 
TApplication.HandleEvent( Event ); 
if Event.What = evCommand then 
begin 
case Event.Command of 
cmNewWin : NewWindow; 
cmSetColors : SetColors; 
else Ext: 
end; {case} 
ClearEvent(CEvent); 
end; 
end; 


The TApplication.HandleEvent method is called with the Event record struc- 
ture and internally handles most event messages, only returning event messages 
for which no internal handling is provided. In this example, there are only two event 
messages which receive local handling: cemNewWin and cmSetColors which call, 
respectively, the NewWindow and SetColors methods. This part of the processing, 
however, only provides a means of calling the SetColors method while the infor- 
mation set in the dialog window is used in another fashion. 


Using the Dialog Settings Information 


The information set in the dialog box, or the default information settings, if the 
Colors dialog has not been called, are used by the TInterior.Init constructor method 
to create a new text window. Each time a new text window is displayed, the Init 
method is called and begins with by setting the background color value in the Color 
variable. 


constructor TInterior.Init( 
begin 


case DiagData.RadButtonData of 
$00 : Color Blue shl 4; 
307 2. Color Green shl 4; 

$02 : Color Red shl 4; 

end; 
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Since the background color was set by a radiobutton selection, the integer value 
in the RadButtonData field is used in a case statement to set the corresponding color 
value ... or to set any other type of value. 

inc(€ Color, DiagData.CheckBoxData or $08 ); 
end; 

In the second instance of the CheckBoxData data which holds the foreground 
color specification as bit-mapped data, no case or decision structure is required in 
this instance because the color buttons were declared in the same order as the 
corresponding color values. The record value already corresponds to the color 
value bit for bit with the exception that the or $08 provision is needed to set the 
high-intensity color bit. 

In other cases, this shortcut may not be available and a bit-wise comparison 
may be necessary to set desired values. In this example, the shortcut works and 
subsequent calls to the TInterior.Draw method will use these color values for the 
text displayed. 

Remember, the Color variable belongs to the TInterior object and, therefore, 
each text window object instance will have its own copy of the Color variable data. 
And, because of this, multiple text windows with different color settings can be 
displayed and each one, when brought to the front or when overlying windows are 
erased, will be redrawn using the appropriate colors. 

Asa hands-on exercise, try creating a large number of text windows using this 
example and then selecting, moving or deleting various windows. Notice how 
quickly underlying windows are recreated, each with the appropriate text and 
background colors. Also notice that several hundred windows can be overlaid 
without losing track of any of them. The actual limit is determined by the available 
memory but is certainly ample for any realistic application. 

Running my own test, I gave up somewhere over 300 windows simply because 
my fingers were getting tired, but I was still able to delete all windows in reverse 
order with all windows uncovered, restored in perfect form. 

Think for a moment about how much code would be required to write a similar 
handling in conventional, non-object code. 


Summary 


I opened this chapter saying that space limitations prevented covering Turbo Vision 
in the length and detail which the subject properly deserves because a comprehen- 
sive treatment would require an entire book of this same length. 
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Instead, | hit a few of the highlights of event-driven programming and showed 
how Turbo Vision operates in creating an example application with windows 
displaying the program source code and a sample dialog box incorporating all 
principal dialog elements. 

The Turbo Vision Guide provides over 400 pages on the Turbo Vision object 
hierarchy with details on predefined messages, event codes, event masks and other 
object elements as well as comprehensive coverage of all of the Turbo Vision objects 
and methods. Perhaps your best references, however, are the example programs, 
both those included in this book and those distributed with Turbo Pascal 6.0. 


{(SHSSSeSeSeseeseSSeeeses rast esSeet ests sesesessessc=zz=} 
{ TVDemo04.PAS } 
{ Turbo Pascal 6.0 == Turbo Vision Example } 
(SSSSeesr tse esse e es essesseeesecsesaseeeseee====} 
uses App, { TApplication object type 
Crt, 
Dialogs, {  TDialog object type 
Dos, 
Drivers, { keyboard events 
Menus, { PStatusLine 
Objects, { TRect object types 
Views; { hcNoContext, etc 
const 
MaxLines = 100; { number of Lines to read 
cmFileOpen = 100; { command message 
cmNewWin = 101; { command message 
cmSetColors = 102; { command message 
WinCount : integer = QO; { initialized variable constant 
type 
WinDialogData = record 


CheckBoxData : word; 
RadButtonData : word; 
WindTitle : stringl20]; 


end; 
(SSSasSSSseSesSeeeeeessessrsessesseseseseez=s===} 
{ TObject -> TView -> TGroup -> Tprogram -> } 
{ TApplication -> ApplObj } 
{ ApplObj supplies the screen handling } 
(SSSSSSSSSesessssesesaeassssseesssesessesses=====} 


ApplObj = object(€ TApplication ) 
procedure HandleEvent( var Event: TEvent ); virtual; 


wwe ey 


Wee YY 


var 
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procedure InitMenuBar; virtual; 
procedure InitStatusLine; virtual; 
procedure SetColors; 

procedure NewWindow; 


end; 
(SHeSSSSSSSSSSSeeteeseezsertesrsssseesezsez=zz} 
€ TOpye¢ct:-=> ~ TV ie. =<) Teeretlter. «> ... 3 
({SSSeSesSSeeS SSS SSeS eee e2reees2r2eeez2e2===}) 


PInterior ST LALO AGL zZ 
Tintertor obiectt TScrot ter 32 
Cotor : byte, 
constructor Init< : ver Bounds: TRect: 
AMS¢rol( Bar, 
AVScrollBar: PScroltBar?: 
procedure Draw; virtual; 
end; 


{ TObject -> TView -> TGroup -> TWindow -> ... } 
{ TWindow owns TFrame, TScroller and one or two } 
{ TScrollBar objects } 


PtrWindow = “*TxtWindow; 
TxtWindow = object( TWindow ) 

Rinterior, Linterior +. Platerter: 

constructor Init(€ Bounds : TRect; 

WindowNo : Word ); 
function MakeInterior( Bounds : TRect; 
Lett: :. Booteand: PIntertor: 

procedure SizeLimits( var Min, Max : TPoint ); virtual; 

end; 


PtrDialog = *TemDialog; 
TemDialog = object( TDialog ) end; 


DiagData : WinDialogData; 
LineCount : integer; 


LinArr >: arraylO..MaxLines-1] of PString; 
{SSSSSS2SSSS2SSSS2SSSeeeeeeesezezee2e2z=ze=}) 
{ Method implementation for TInterior } 
{(SSSSeSssSSeS Se SeeeSSeSeeeeseeeezezcezz==) 


constructor TInterior.Init(€ var Bounds : TRect; 


AHScrollBar, 
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AVSerottBer:: oPSerel tBar:); 
begin 
TScroltler.Init¢ Bounds, AHScroltBar, AVScrotlBar >); 
Options := Options or ofFramed; 
Seti tate 128, LineCcount 2; 
case DiagData.RadButtonData of 
SU0.:3.°Cotor Blue shl 4; 
S01 2% "Color Green shl 4; 
Se 3: Cotor Red shl 4; 
end; 
inc€ Color, DiagData.CheckBoxData or $08 ); 
end; 


procedure TInterior.Draw; 
var 

i, J: Enteger> 

Buf: TDrawBuffer; 
begin 

TScroller.Draw; 

for > - te. to. Stze.7=7T -do 


begin 
Movechnar( Sut, > totor,: Stre.xrk 7s 
12a Bet teurer: 
140.4 °* CinetCount and © tbandtrresyd <> Nit) then 
MoveStr 
( Buf, 
Copy -Lindrrtir, ‘Dettacte}, Sizve<«x 2, 
Color 
); 
Ori tettone t 0,  f)°S108. xX, 1; Bet. 2s 
end; 
end; 
{aesesesStseesz assess sescresesesetestessseeszaecs=) 
{ implementation for TDemoWindow methods } 
{SeseeeSee2S Se SSaeSeteeesserssssseseseeresses=} 


constructor TxtWindow.Init(€ Bounds: TRect; 
WindowNo: Word ); 
var 
NGQ<cs:-etringtsd; 
Ree i: TReet: 
begin 
Stet WiandowNo, NSt )> 
TWindow.Init(¢ Bounds, 
DiagData.WindTitle + ' * + NSt, 
wnNoNumber ); 
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GetExtent( Bounds ); 

Rec.Assign( Bounds.A.X, Bounds.A.Y, 
Bounds.B.X div 2+1, Bounds.B.Y ); 

LInterior := MakeInterior( Rec, True ); 

LIinterior*.GrowMode := gfGrowHiY; 

insert(t Linteritor 3. 

Rec.Assign( Bounds.B.X div 2, Bounds.A.Y, 
Bounds.68.X, Bounds.B.Y 3 

RInterior := MakeInterior( Rec, False ); 

RInterior*.GrowMode := gfGrowHiX + gfGrowHiY; 

Insert( RInterior ); 

end; 


function TxtWindow.MakeInterior( Bounds: TRect; 
Left: Boolean ): Pinteritor; 
var 
HScrollBar, VScrollBars: PScrollBar; 
Rec: TRect; 
begin 
Rec.Assign( Bounds.B.X-1, Bounds.A.Yt1, 
Bounds.B.X, Bounds.B.Y~-1 ); 
VScrollBar := New( PScrollBar, Init( Rec ) ); 
VScrollBar*.Options :2 VScrollBar* Options or: of PostProcess; 
if Left then VScrollBar*.GrowMode := gfGrowHiY; 
Insert( VScrollBar ); 
Rec.Assign( Bounds.A.X+2, Bounds.B.Y-1, 
Bounds.B.X-2, Bounds.B.Y : 
HScrollBar := New( PScrollBar, Init Rec ) ); 
HScrollBar*.Options := 
HScrollBar*.Options or ofPostProcess; 
if Left then 
HScrollBar*.GrowMode := gfGrowHiY + gfGrowLoyY; 
Insert( HScrollBar ); 
Bounds.Grow(-1,-1); 
MakeInterior := 
New( PInterior, 
Init¢ Bounds, HScrollBar, VScrollBar ) ); 
end; 


procedure TxtWindow.SizeLimits( var Min, Max: TPoint ); 
var 
ROC? TREC 7 
begin 
TWindow.SizeLimits( Min, Max ); 
MAnwX 2*@ Linterior®.Size.x%-+. 93 
end; 
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{=xeBecretsesssesczerssseetsesesesressseses} 
{ implementation for ApplObj methods } 
{SS eesSeesecSeesecctscatstestascscsteseresaas2 =} 
procedure ApplObj.HandleEvent( var Event: TEvent ); 
begin 
TApplication.HandleEvent( Event ); 
if Event.What = evCommand then 
begin 
case Event.Command of 
cmNewWin >: NewWindow; 
cmsetColors : SetColtlors: 
else Exit; 
end; {case} 
ClearEvent(Event); 
end; 
end; 


procedure ApplObj.InitMenuBar; 
var 
Rec: TRect; 
begin 
GetExtent( Rec ); 
RGC.oat t= Rec. Aw. + 3 
MenuBar := 


New 
( PMenuBar, 
[nit 
GRO. 
NewMenu 
( NewSubMenu 
( et Se 
hcNoContext, 
NewMenu 


( NewIltem 
( oe BON 4. FS oo ROES:, 
cmFileOpen, hcNoContext, 
NewItem 
( RN VOWS DEST. RB ERG 
cmNewWin, hcNoContext, 
NewLine 
( NewItem 
( Rig Ae. EDA EZ, 
cmQuit, hcNoContext, 
; ; ; : . NIL 
) ) ) ) ay 
NewSubMenu 
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( '"W~ indow', hcNoContext, 
NewMenu 
( Newltem 
( ON ext", *F6%?4-KeFRz 
cmNext, hcNoContext, 


NewItem 

( te 2 Oe 3h) PES 4 3 BOF SS 
cmZoom, hcNoContext, 
NewIltem 


( CTC @etors*, “Fa"s. kKbFe, 
cmSetColors, hcNoContext, 
. : ‘ NIL 
) ) ) dy 
; ‘ ‘ ‘ ‘ NIL 
) ) ) ) 3 
end; 
procedure ApplObj.InitStatusLine; 
var 
Rec: TRect; 
begin 
GetExtent (Rec); 
Rec.A.Y = Reoc.8.Y = 13 
StatusLine := 


New 
( PStatusLine, 
ind 
( Rec, 
NewStatusDef 
C 0, StE, 
NewStatusKey 
( rt 6©KbFIT0O, cmMenu, 
NewStatusKey 
( AL ERR CERT ES 
kbALtX, cmQuit, 
NewStatusKey 
( '""F4~ View', 
kbF4, cmNewWin, 
NewStatusKey 
( NAL tHFES- Chess; 
kbALtF3, cmClose, 
: ‘ ‘ NIL 
) ) ) : Os 
: NIL 
) ) F- 


end; 
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procedure ApplObj.SetColors; 
var 
PtrView : PView; 
Dialog : PtrDdialog: 
ROC ts "TRECs 


begin 
Rec. A883 606° 20,6, 60, 48273 1inet; TReet Assign 3 
Dialog := 


New( PtrDialog, Init( Rec, ‘Color Settings Demo' ) ); 
with Dialog%* do 
begin 
REG,ASStgnt 2, 3, .19, 6°25 
PtrView := 
New(€ PCheckBoxes, 
raittc Res, 
NewSItem(€ ‘Light “~B™lue', 
NewSItem(€ ‘Light “~“G”reen', 
NewSItem(€ ‘Light “~Red', 
Net iD 
) re 
Enesertc PtrView:)>; 


Rec Asaetenk:! 15 235495. 3.48 
Insert (¢ 
New(€ PLabel, 
Init€ Rec, ‘Foreground Colors', PtrView ) ) ): 


Rec ASEtont. 22, 3, 68, 6329 
PtrView := 
New€ PRadioButtons, 
Init(€ Rec, 
NewSItem( ‘Dark Bl "u’e', 
NewSItem(€ ‘Dark Gr“e“en', 
NewSItem(€ ‘Dark Re“d7', 
NIL ) ) ) 
) rs 

Insert ¢ PtrView ); 

Rec. ASeiont 21,25 38; 3°33 

Insert (¢ 


New(€ PLabel, 
Init€ Rec, ‘Background Color', PtrView ) ) ); 


Rec.Assign( Tey ace Be few? 
PtrView := New( PInputLine, 
Init(€ Rec, 


sizeof(€ DiagData.WindTitle ) ) ); 
Insert PtrView ): 
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Rec. Assign ( Yoo Fe teg = B23 
Insert (¢ 
New( PLabel, 
Init( Rec, ‘Window Caption:', PtrView ) ) ); 


Rec.Assign( Ls: we eee, cee 
Insert (¢ 
New( PButton, 
Teitt Recy '7O°K" > cmOk, BTDETaUlLt 2 2 23 


Rec ASS iont £85. Fy) SE, 17 5 
Insert (¢ 
New( PButton, 
Init( Rec, 'Cancel', cmCancel, bfNormal ) ) ); 
end; 


Dialog*.SetData( DiagData ); 
if DeskTop*.ExecView( Dialog ) <> cmCancel then 
Dialog*.GetData( DiagData ); 
Dispose( Dialog, Done ); 
end; 


procedure ApplObj.NewWindow,; 
var 
Window: PtrWindow; 
Recs TRect; 
begin 
inc( Win€ount 2; 
Rec. Assiaqnt Q,-0,; 45, 16-23% 
Rec.Move( Random( 34 ), Random(€ 11 ) ); 
Window := New( PtrWindow, Init(€ Rec, WinCount ) ); 
DeskTop*.Insert( Window ); 


end; 
{seseeesssresssezee===} 
{ object methods end } 
{seeeeessesseseses=s=} 
procedure ReadFile( FileToRead: PathStr 3 
var 


FIL *€ Text; 
1St & otritrng; 

begin 
LineCount := 0O; 
Assign( Fil, FileToRead ); 
{$I1-} Reset( Fil ); {$I+} 
if I10result <> O then 
begin 


740 USING TURBO PASCAL 6.0 





{ optional error handling here } 
end else 


begin 
While not EofC( Fil) and € LineCount < MaxLines ) do 
begin 
Remaint Fit,’ FSt.d) 
LinArrCLineCount] := NewStr( TSt ); 
inc€ LineCount ); 
end; 
Ctoset Fil ); 
end; 
end; 


procedure DoneFile; 
var 
i: Integer; 
begin 
for i := 0 to LineCount-1 do 
if LinArrlCil <> NIL then DisposeStr( LinArrLil 3 
end; 


var 
DemoApp: ApplObj; 


begin 
CLirgers 
with DiagData do 
begin 
CheckBoxData = $07; 
RadButtonData := $01; 


WindTitle := 'Text Window'; 
end; 
ReadFile(€ "TVDEMOO4.PAS' ); 
with DemoApp do 
begin 
intt: 
Run; 
Done; 
end; 
DoneFile; 
end. 


Appendix A 


OOP Terminology 


Abstract Data Types A set of data structures (data types) defined strictly in terms 
of the features of the structures and the operations executed on these structures. In 
OOP, Object Types (that is, classes) are abstract data types. 


Ancestor Type Any type from which another object type inherits. See also Imme- 
diate Ancestor. 


Binding The process by which the address of a procedure is given to the caller. 
This may be early binding occurring at compile/link time or late binding occur- 
ring at run time when the procedure is called. Traditional compilers such as C and 
Pascal support early binding only, while C++ and OS/2 (.DLL libraries) compilers 
support both early and late binding. See also Early Binding and Late Binding. 


C++ Anobject-oriented superset extension to the C compiler language developed 
by Bjarne Stroustrup. 


Classes Term used by Smalltalk and others—synonymous with object types. 


Client Relationship Not implemented in object-oriented Turbo Pascal. In other 
OOP systems, objects may be clients of other objects in addition to the inheritance 
relationship. Aclient relationship means that the implementation of the client object 
(class) relies on the implementation of the supplier object (class). 


74] 


742 USING TURBO PASCAL 6.0 








Concurrency Not implemented by DOS languages at present, concurrency is a 
potential implementation of object-oriented programming for systems employing 
concurrent or parallel processors or multitasking systems such as OS/2. The 
capability of object-oriented programs to communicate by messages removes some 
of the difficulty of synchronization between concurrent or parallel processes. For 
examples, see OS/2, but note that while OS/2 uses object-oriented programming 
methods, it is not recommended as a good example of how object-oriented pro- 
gramming should be implemented. 


Constructor A special type of method—defined by the reserved word construc- 
tor—which initializes an object containing virtual methods. An instance’s con- 
structor must be called before calling its virtual methods; otherwise, a run-time 
error will occur. 


Descendant Type Any type that inherits from an object type. See also Inheritance. 


Destructor A special type of method. This is defined by the reserved word 
destructor—which determines the size of an object, at run-time, immediately 
before deallocating the object from the heap. Destructors allow polymorphic 
objects to be correctly deallocated, even though their exact type and; therefore, exact 
size, is not known at compile time. 


Dynamic Binding Late or delayed binding. See Late Binding. 


Dynamic Instance Any object instance that is created by dynamic memory alloca- 
tion. See also Static Instance. 


Early Binding ‘The traditional method of compiling in which the addresses of 
procedures or functions are determined at compile/link time. Object-oriented 
language compilers, however, may use late binding in which the procedures’ 
address code is not known at compile/link time, but is only determined at run time 
when the procedure is actually called. See also Virtual Methods. 


Encapsulation The wedding of code to data within an object unit. This is modu- 
larity applied to data—combining records with procedures and functions that 
manipulate data to form a new data type which is called an object. Encapsulation 
renders an object’s data “invisible” to the user of the object while the methods for 
manipulating the data remain “visible.” 
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Extensibility A feature allowing the user of object-oriented code to extend the code 
without having the source code. Descendant object types can be made to inherit the 
ancestor object type’s properties even though the ancestor object type belongs to 
an externally compiled module. Extensibility allows sharing or selling object librar- 
ies without revealing trade secrets or algorithms. Also, extensibility allows existing 
objects to be customized for new applications by extending these as new object 


types. 


Hybrid Paradigms Somesystems suchas Smalltalk (and OS/2) are pure object-ori- 
ented programming systems, operating solely by message passing. Others such as 
Object Pascal, Objective C or C++ are hybrids which provide both OOP and 
non-OOP programming features. Hybrids are popular largely for ease of develop- 
ment, the presence of familiar capabilities and speed in execution and creation. 


Immediate Ancestor An object type may have several ancestors, but the ancestor 
named in the object’s type definition is the type’s immediate ancestor. See also 
ancestor type. 


Information Hiding Information hiding is a feature of modular programming in 
which the information within a module is private to the module except as made 
public through an interface definition (method). See Encapsulation. 


Inheritance The property of all object types that allows a type to be defined which 
“inherits” all data and method definitions that were contained in a previously 
defined type. It does so without restating these definitions. Any type inheriting 
from another type is called a descendant type. Inheritance is a property of objects, 
allowing creation of a hierarchy of objects with descendants of objects implicitly 
inheriting access to their ancestors’ code and data structures. 


Instance A variable of type object or an instance of a specific object type. Also, in 
conventional usage, the term object refers to an instance of an object type. 


Late Binding A method of calling procedures in which the address of the proce- 
dure—the address to which control is passed when the procedure is called—is not 
known at compile/link time and is only determined at run time when the procedure 
is actually called. Late binding is characteristic of object-oriented language compil- 
ers and, in conjunction with inheritance, late binding makes polymorphism pos- 
sible. See also Early Binding and Virtual Methods. 
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Messages Action parameters or orders passed to object calls, instructing the 
object to execute specific capabilities or features. 


Method A procedure or function which is defined as belonging to an object type. 
Methods may be static or virtual. 


Modularity Program construction in modules, blocks or units that are combined 
to build complete programs. Ideally, the redesign or reimplementation of a unit or 
module can be accomplished without affecting the operation of the rest of the 
program or system. The DOS, CRT and GRAPH units in Turbo Pascal and Turbo C 
are good examples of modularity, while other unit examples are shown and 
developed in this book. Modularity is one of the primary objects of object-oriented 
programming. 


Multiple Inheritance © Not implemented in Object Pascal. A few OOP systems (such 
as Eiffel) possess multiple inheritance, allowing an object to inherit features and 
data from two or more ancestor objects. With single inheritance, the inheritance 
structure is a tree. With multiple inheritance, the inheritance structure is a web or 
maze with multiple ancestors contributing separate data and methods (comple- 
mentary). They may contribute identical or entirely different versions of the same 
method, the latter case generally leading to confusion. 


Object Reserved word indicating object type definition or any variable of an 
object type—may also be called an instance of an object type. 


Object Hierarchy A group of object types related through inheritance. The Turbo 
Debugger, executing an object-oriented module, can be used to display a graphic 
representation of an object hierarchy by selecting Views, Hierarchy from the menu. 


Object Type A special structure that may contain procedure and function defini- 
tions—called methods. The object type structure is similar to the Pascal record 
structure. Object types may be defined as including all data and method definitions 
which were defined within some previously object type. See Ancestor Type, 
Descendant Type and Inheritance. 


Object-oriented Term for programming practices or compilers that collect indi- 
vidual programming elements into hierarchies of classes, allowing program objects 
to share access to data and procedures without redefinition. 
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Polymorphic Object An instance of an object with a descendant object is a poly- 
morphic object because the descendant object inherits the “shape” of any of the 
ancestor type, but can “polymorph” into a new “shape.” 


Polymorphism Polymorphism is the property of sharing a single action (and 
action name) throughout an object hierarchy, but with each object in the hierarchy 
implementing the action in a manner appropriate to its specific requirements. 


Range Checking ($R) In Turbo Pascal 5.5, the $R+ compiler option (active) tests 
the initialization status of all object instances making virtual methods calls that 
prevent uninitialized calls from producing a system hang up. After a program is 
debugged, the $R- (inactive) setting can be used to speed program execution. 


Redefinition The mechanism which allows the client programmer to employ the 
same name to refer to different things depending on the class to which each is 
applied. For example, both Point and Circle possess the property of location, but 
this property may be redefined from one object to the next. For Point, location 
would bea single pixel on the screen, but for Circle, location may be either the center 
of the circle or the corner of the screen rectangle in which the circle was created. See 
also Selective Inheritance. 


Repeated Inheritance Not implemented in Object Pascal. Repeated inheritance is 
a special case of multiple inheritance in which an object D is the descendant of A 
by more than one path. 


Reusability A principal feature and objective of object-oriented programming, to 
allow software to be reused instead of reinvented. Libraries and include files are 
early examples of reusability, while the Turbo Pascal Units (TPUs) are a later 
development. 


Selective Inheritance Not implemented by Object Pascal (or by anyone else), 
selective inheritance would allow objects to discard data or features belonging to 
their ancestor objects. Currently, redefinition is the only method of changing 
inheritance features, but selective inheritance may appear at a later time. 


Self. An invisible identifier which is automatically declared within an object— 
may be used to resolve identifier conflicts by qualifying data fields belonging to an 
method ’s object. 
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Simula-67 The original object-oriented language, Simula-67 was designed for 
writing test simulations of physical objects such as mechanical devices. 


Smalltalk An early object-oriented language, Smalltalk is an interpreter language 
(like BASIC), not a compiler. 


Static Instance Any instance of an object which is named ina var declaration and, 
therefore, is statically allocated in the stack and data segment. See also Dynamic 
Instance. 


Static Method A method implemented using early binding. The method’s 
address is determined at compile/link time, just as the address of any conventional 
procedure or function is known at compile time. Static method calls require less 
overhead and should be used as optimization when the flexibility of virtual 
methods is not required. 


Static Object Similar to static data definitions, static object definitions are allowed 
in C++, but not in Object Pascal. See also Static Instance. 


Types Templates or definitions for creating objects. 


Virtual Method Any method implemented with late binding by using the 
reserved word virtual. In actual operation, a virtual method is usually a group of 
methods with identical procedure or function headers within an object hierarchy. 
When a virtual method is executed, a special mechanism determines which imple- 
mentation of the virtual method is appropriate to the object type of the calling 
instance. The selection mechanism is installed by calling the object’s constructor. 


Virtual Method Table (VMT) A table appearing in each virtual object type’s data 
segment. The VMT contains the size of the object type (record size) and pointers to 
the procedures and functions implementing the object type’s methods. Each object 
instance’s constructor creates a link between the calling instance and the VMT, with 
the VMT used to call the method implementations. 


Appendix B 


The Object Mouse Utility 


The Object Mouse unit (MOUSE.TPU) is an object-oriented mouse unit for use with 
Turbo Pascal application programs. It supplies four mouse types for general use: a 
graphics mouse, text mouse, and both graphics and text lightpen mouse object 
types that provide the following procedures and functions: 


General Mouse Object Procedures 

GetPosition Reports mouse position and button status (all). 
QueryBtnDn Reports requested button down event and position. 
QueryBtnUp Reports requested button up event and position. 
ReadMove Reports mouse movement. 

Reset Resets mouse to default status. 

SetAccel Sets acceleration point for enhanced mouse movement. 
SetLimits Restricts mouse movement to selected screen area. 
SetPosition Sets position of mouse cursor on screen. 


SetRatio Sets ratio of physical mouse movement to screen movement. 
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TestMouse Reports mouse and driver present on system. 


Show Shows or hides mouse cursor. 


Text Mouse Object Procedures 
Initialize Sets initial conditions for text mouse. 


SetCursor Sets hardware or software text cursor. 


Graphic Mouse Object Procedures 
ConditionalHide Selects screen area where graphic cursor is hidden. 
Initialize Sets initial conditions for graphic mouse. 


SetCursor Selects graphics mouse cursor. 


LightPen Mouse Object Procedures 


LightPen Enables or disables lightpen emulation for both text and graphics 
lightpen mouse objects. 


The type definitions for each mouse are available to any application program 
including the statement uses Mouse in the header, but each application must 
declare a local variable using one of the following appropriate types: 


var 
TMouse = TextMouse; { standard text mouse 
GMouse = GraphicMouse; { standard graphics mouse 
LTMouse = TextLightPen; { text with Lightpen 
LGMouse = GraphicLightPen; { graphic with Lightpen 


General Mouse Procedures and Functions 


Many of the procedure and functions supplied by the mouse unit are common to 
all of the object mouse types. Two record structures and seven constants are also 
defined globally in the mouse unit and are available to the application using the 
mouse unit. 


ww Y we 
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The first structure, defined as type Position, is used by all mouse object types 
to report mouse button events: 


type 
Position = record 
BtnStatus, 
opCtount, 
xPos, yPos : integer; 
end; 


The second structure, defined as type GCursor, is used by the GraphicMouse 
object type to set the graphics mouse cursor: 


type 
GCursor = record 
ScreenMask, 
CursorMask : arraytU. 2tss oF word: 
hotX, hotY : integer; 
end; 


The seven constants shown in Table B-1 are globally defined by the mouse. 


Table B-1: Mouse Constants 
Constant Value Application 


ButtonL 0 left button 

ButtonR 1 right button 

ButtonM 2 middle button 

Software 0 used to set software text cursor 
Hardware 1 used to set hardware text cursor 
TestMouse 


The TestMouse function returns a boolean result indicating the presence or absence 
of a mouse driver in the system. This is generally used by an application to 
determine if a mouse is already in use. For most applications, the Reset procedure 
is preferred. 


Reset 


The Reset procedure is used to reset the mouse driver to its default state. Two 
arguments are required, returning a Boolean status and the number of buttons 
supported by the physical mouse. The procedure is called as: 


var 
Status : Boolean; 
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BtnCount : integer; 


GMouse.Reset( Status, BtnCount ); 


Status will return TRUE if the mouse and mouse driver are present and 
installed; FALSE if the mouse cannot be used. BtnCount will return with a value of 
2 or 3 indicating the number of buttons supported by the physical mouse. 

In graphics applications, the default mouse cursor is enabled by the Reset 
function, but see also the Initialize procedure supplied by the GraphicMouse. 


Show 


The Show procedure is used to turn the mouse cursor on or off and is called with 
a single boolean argument specifying the desired state. The Show procedure is 
called as: 


GMouse.Show( TRUE ) { shows mouse cursor } 
GMouse.Show( FALSE ) { hides mouse cursor ) 


Initially, the mouse cursor is always hidden and must be explicitly rendered 
visible. The visible or invisible state of the mouse, however, does not affect tracking 
the mouse position or reporting on mouse button events. 

Note: conventional mouse Show and Hide functions decrement or increment a 
cursor counter such that two or more calls to hide the mouse cursor will require 
two or more calls to make the mouse cursor visible again and vice versa. The object 
mouse avoids this potential problem and multiple calls to Show(ON) do not require 
multiple calls to Show(OFF). 


GetPosition 


The GetPosition procedure is called with three integer arguments: BtnStatus, XPos 
and YPos. These are returned with the current status of the mouse buttons and the 
x- and y-axis mouse pointer coordinates and are called as: 


var 
BtnStatus, XPos, YPos : integer; 


GMouse.GetPosition( BtnStatus, XPos, YPos ) 


The BtnStatus variable returns with the three least-significant-bits—beginning 
with bit 0—indicating the status of the left, right and middle buttons respectively. 
If the button is down, the bit is set. If the button is up, the bit is cleared. The XPos 
and YPos variables return the current screen coordinates of the mouse cursor. 
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In text modes, the coordinates are always returned in incremental steps deter- 
mined by the character cell width and height, but are still in pixel coordinates. For 
example, if the system is in text mode and the mouse cursor is in the third column, 
second row, the coordinates returned would be 24, 16 (assuming an 8x8 character 
cell). In graphics modes, the coordinates returned are the pixel coordinates of the 
graphics cursor’s hotspot. 

See also QueryBtnDn, QueryBtnUp and SetLimits. 


SetPosition 


The SetPosition procedure allows the application program to position the mouse 
cursor independent of the movement of the physical mouse. The SetPosition 
function is called with two integer arguments establishing the x- and y-axis position 
for the mouse cursor: 


GMouse.SetPosition( 315, 200 ); 


In text modes, the x- and y-axis coordinates are rounded to the nearest character 
boundaries in pixel coordinates. Assuming an 8x8 character cell, the arguments 
shown would position the cursor at column 39, row 25. In graphics modes, the 
mouse cursor would be positioned with the cursor hotspot at the specified coordi- 
nates. 

All subsequent movements generated by the physical mouse will begin at the 
location established by the SetPosition function. 


QueryBtnDn and QueryBtnUp 


The QueryBtnDn and QueryBtnUp procedures require two arguments: a integer 
argument selecting the mouse button to be reported and a variable of type Position 
(globally defined by the mouse unit) which returns the button status, event count 
and coordinates of the button event requested. 

QueryBtnDn reports button pressed events; QueryBtnUp reports button 
released events. 


var 
BtnEvent : Position; 


QueryBtnDn( ButtonL, BtnEvent ); 
QueryBtnUp( ButtonM, BtnEvent ); 


The returned BtnEvent structure reports the number of times (if any) the 
queried button has been pressed (or released), the current status (up or down) of 
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the queried button, and the screen coordinates of the mouse cursor when the most 
recent button event occurred. 

The button event counter—for the specific button and type of event—is reset 
by this call. 


ReadMove 


The ReadMove procedure requires two integer arguments to return the horizontal 
and vertical step counts. The values returned are always in the range -32768..32767 
with positive counts indicating motion from left to right or from top to bottom: 


var 
XMove, YMove : integer; 


ReadMove( XMove, YMove ); 


The horizontal and vertical step counters are reset to zero by this call. See also 
SetAccel. 


SetAccel 


The SetAccel procedure is used to set a physical speed threshold (in mickeys/sec- 
ond) over which the mouse driver adds an acceleration component. With an 
acceleration threshold set, fast mouse movements move the cursor further than 
slow movements over the same physical distance, allowing fine positioning by slow 
movements and broad changes with fast movements: 


SetAccel¢ S00 >>; 

Mouse acceleration can be disabled by setting an arbitrarily high threshold 
value (such as 7FFFh). See also SetRatio. 
SetLimits 


The SetLimits procedure sets minimum and maximum screen limits, restricting 
cursor movement to the selected area. If the cursor is outside the area set, the cursor 
is immediately moved just inside the new borders: 


SetLimits( 0, 0, GetMaxX, GetMaxY ); 


The shown call sets the mouse boundaries to cover the entire graphics screen. 
If either minimum value is greater than the corresponding maximum, the two 
values are swapped. 
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SetRatio 


The SetRatio procedure uses two integer arguments to set the ratio of physical 
mouse motion to horizontal and vertical screen mouse motion: 


SetRatio(€ 16, 16 ); 


Default movement ratios are 8 mickeys (units of physical movement) to 8 pixels 
horizontal and 16 mickeys to 8 pixels vertical. Ratio values may be in the range 
1..32767 mickeys. See also SetAccel. 


The Text Mouse Object 


The Text Mouse object includes all of the general mouse procedures with one 
addition: 


SetCursor 


The SetCursor procedure is used to select either a Software or Hardware text cursor 
and to set the cursor style. The Software and Hardware constants are predefined 
by the mouse unit. 

If the Hardware cursor is selected, the second and third parameters specify the 
start and stop scan lines for the cursor: 


SetCursor( Hardware, 8, f I; 


If the Software cursor is selected, the second and third parameters set the screen 
and cursor masks: 


SetCursor( Software, $0000, $8F18 ); 


The Graphic Mouse Object 


For the graphics mouse, the SetCursor procedure is also implemented, but in a 
different form from the text mouse. Two additional graphics procedures— 
ConditionalHide and Initialize—are provided as well. 


ConditionalHide 


The ConditionalHide procedure is called with four integer parameters: left, top, 
right and bottom, in this order—establishing an area of the screen where the mouse 
cursor is automatically concealed: 
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var 
Left. t96) right, hottonm.s. integer; 


Condit tonethidet Lett, top, right, bottom >; 


The ConditionalHide procedure can be used to guard an area of the screen 
which is about to be repainted. If the mouse is in the area selected, the cursor visible 
counter is decremented just as if Show( OFF ) was called. 

Any subsequent call to Show( ON ) reenables the cursor within the entire region 
established by the SetLimits procedure. 


Initialize: 


The Initialize procedure is called without parameters and provides a convenient 
method of setting initial conditions for a graphics mouse: 


Initialize; 

The Initialize procedure enables mouse movement over the entire graphics 
screen, selects the arrow cursor, renders the cursor visible and positions the mouse 
at the center of the screen. 


SetCursor 


With the graphics mouse, the SetCursor procedure is slightly different than with 
the text mouse and is called with a single parameter that must be type GCursor as 
defined in the mouse unit: 


SetCursor€ e@errow:); 
Five graphic cursors are predefined in the mouse unit, including arrow, check, 


cross, glove and ibeam, the latter four appear in Figure B-1. 


Figure B-1:; Four Graphic Mouse Cursors 
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Additional graphics cursors can be created using the MOUSEPTR utility and 
may be included directly in the application program or added to the mouse unit. 


The LightPen Mouse Object 


Two versions of the LightPen Mouse are provided by the mouse unit: TextLightPen 
and GraphicLightPen. These are descendants, respectively, of the text and graphics 
mouse objects, but add lightpen handing to each. 


LightPen 


The LightPen procedure is the same for both text and graphics versions and is called 
with a single Boolean parameter to either enable or disable lightpen emulation by 
the mouse: 


LightPen( TRUE ); { Lightpen enabled} 
LightPen(€ FALSE ); { Lightpen disabled } 
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@ operator, 75 

.. \ (Parent directory specification), 34 
{$F+} directive, 337 

{$I-} statement, 151-152 

($I include directive, 284 

{$O overlay directive, 337-338 
{SI+} statement, 151-152 

$M compiler directive, 18, 269-270 
$R compiler directive, 18 

286 option, 17 

8087/80287 option, 17-18 


About dialog box, 16 
Abs function, 83 
Absolute pathname, 20 
Active directory, returning, 185-186 
Add watch option, 23 
AddBar function, 470-471 
AddData function, 129 
Addr function, 274 
Address operators, memory, 274-276 
Addresses 
internal register, 277-278 
offset, 275-276 
Advanced mathematical operations, 
79-90 
Alt-keys, selecting menus, 16 
AndPut option, 415 
Append procedure, 163 
Applications, Turbo Vision, 708-710 
ApplObj.SetColors method, 726-727 
AppObj procedure, 710-711 
Arc procedure, 405 
Arcs, drawing, 403-408 
ArcTan function, 80, 84 
Arithmetic operators, 70-71 


Arrays 

data, 63-64 

defining as constants, 138-139 

KeepScreen, 287 

Mem, 277 

MemL, 277 

MemW, 277 

Numbers, 64 

Text, 64 
ASCII character set, 50-53, 218-220 
Assign procedure, 164 
AssignCrt procedure (CRT), 164-165 
Assignment (=) operator, 76 
Attributes, system video, 493 
Auto Save option, 21 
AUTOEXEC.BAT file, modifying 

PATH statement, 9-11 

Autoindent mode option, 22 
AX register, 252 


Backspace unindents option, 22 
Bar graphs, 454-458 
assigning colors, 469-470 
drawing, 398-402 
multiple, 458-461 
positioning bars, 470-471 
Bar procedure, 399 
Bar3D function, 463 
Bar3D procedure, 399-400 
BarGraph function, 454 
begin..end statement, 110-111 
BGILINK.MAK file, 429 
Binary operators, 69-70 
Binary tree 
applications, 676-679 
building, 680-681 


Index 


disposing of, 681-682 
implementing, 679-680 
objects, 673-702 
printing, 682-683 
removing items, 686-688 
searches, 683-686 
structures, 673-676 
BIOS interrupts, 249 
BlankLine variable, 450-451 
BlockRead function, 155-157 
BlockRead procedure, 165 
BlockWrite procedure, 155-157, 
165-166 
Boolean 
evaluation, 72-73 
operators, 72, 77-78 
parameters, 99-100 
Box object, methods, 584-587 
Brace characters {}, 47 
Bracket [], in dialog boxes, 17 
Breakpoint option, 23 
BtnTest.PAS program, 605-608 
BTNTEST2.PAS program, 622 
BINTEST3.PAS program, 634-635 
Buffer variable, 155-156 
Buffers, flushing, 167 
BufSize variable, 155-156 
Build option, 38-39 
Business graphic displays, 447-492 
BUTTON2.PAS program, 619-622 
Button3.PAS program, 632-634 
Button4.PAS program, 654-655 
Buttons 
Change all, 29 
Close, 26 
graphic, 581 


Si 
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Buttons (continued) 
Help, 26 
object-oriented programming, 
556-558, 579-608 
Replace, 35 
text, 580-581 
unit, 586-593 
Buttons.PAS program, 594-600 
Bytes, copying between addresses, 276 


CALL command, DOS, 12 
Carry flag, 251-252 
Case sensitive option, 29 
case..of statement, 112-114 
CGA 

color 

palette, 495-496 
values, 494 

high resolution, 496 

snow checking option, 24 

video adapter, 494-496 
CH register, 255 
Change all button, 29 
Change dir option, 34 
Character parameters, 97 
Characters 

(**) (parenthesis /asterisk), 47 

{} (Brace), 47 

ASCII, 50-53 

converting case, 106-107 

ODh (terminating carriage 

return), 153 

writing non-keyboard, 218-220 
ChDir procedure, 184 
Check2.PAS record, 141-144 
Check3.PAS program, 176-179 
Checkboxes, in dialog boxes, 17 
CheckKbd procedure, 290 
Child.PAS program, 260 
chr function, 60, 100 
Circle procedure, 404-405 
Circles, drawing, 403-408 
CL register, 255 
ClearDevice procedure, 375-376 
ClearViewPort procedure, 376 
Close button, 26 
Close instruction, 154 


Close procedure, 166 
CloseGraph procedure, 367 
ClrEol procedure, 209 
ClrSer procedure, 49, 208 
Clusters, dialog box, 727-728 
Code generation options, 17-18 
Codes 
graphic error, 362 
indented, 49-50 
overlay result, 343 
source, 31-32, 283-285 
COLCUBE.C program, 500-506 
Color 
byte organization, 213 
displays, 212-217 
restoring settings, 215 
functions, 381-388 
relations cube, 500-506 
selecting high/low intensity, 215 
values, Video graphics, 385 
ColorCub.PAS program, 506-509 
Colors dialog box, 25 
Colors options, 25 
Colors.PAS program, 509-512 
ColorWheel procedure, 502, 504 
Command line parameters 
accessing, 232-234 
DOS, 231-234 
testing, 234-235 
Commands 
see also Options 
DOS 
CALL, 12 
COPY, 340 
PATH, 9-12 
Edit/Copy Example, 26 
File / New, 33 
Files/Save as, 33-34 
Help/Index, 26 
Retrieve Options, 25 
Run/Run, 40-41 
Save Options, 25 
Search/Find, 29 
Search/ Replace, 29 
seek, 158 
Step over, 40-41 


TextMode, 206 
Trace into, 40-41 
Turbo Editor, 27-28 
Comment identifiers, 48 
Comments, 47-48 
Compile option, 36 
Compiler directives 
$M, 18, 269-270 
$R, 18 
Compiler languages, 32 
Compiler menu, 40 
Compiler options, 17, 38-39 
Compiler Options dialog box, 17-18 
Compiler Options menu, 347-348 
Compilers 
overview, 1-2 
terminating execution, 41 
Compiling programs, 36-37 
Complete evaluation, 73 
Concat function, 100-101 
Conditional defines input box, 18 
Conditional statements, 111-115 
Conditional Hide function, 550 
Config File Directory option, 22 
CONFIG.SYS file, modifying during 
installation, 6, 9 
Configuration options, 16-20 
Console (CRT), associating with text 
files, 164 
Constant declarations, 65 
Constants 
defining arrays as, 138-139 
flag, 251 
string, 67 
text color, 214 
Constructor methods, 629-631 
Contiguous bytes, filling with a 
selected value, 102 
Control-break interruptions, DOS, 239- 
240 
Conventions, program naming, 50-53 
Conversions 
integer-to-string, 437 
real-to-string, 437-438 
Coprocessor support options, 17-18 
Copy function, 101 


COPY command (DOS), 340 
CopyPut option, 414 
Cos function, 80, 84 
Count variable, 156 
CPUs, performance with Code 
generation options, 17-18 
CpyBlock.PAS program, 174-175 
Create backup files option, 22 
Createlmages function, 472-474 
CRT unit, 203-205 
flags and variables, 217-218 
special effects, 220-221 
CS register, returning current value, 
277-278 
CSeg function, 277-278 
Ctrl-C. PAS program, 264 
CUR file extension, 554-555 
Current directory, returning, 185-186 
Current directory option, 22 
Current window option, 21 
Cursor Mask options, 554 
Cursor through tabs option, 22 
Cursors 
mouse graphics, 541-542 
reading position, 207 
Curves, drawing, 403-408 
CustomError function, 346-347 


Data 
arrays, 63-64 
fields, inheriting, 616 
identifying, 64-66 
pointers, using, 292-295 
prompting for input, 132-133 
structures, 128 
fields, 129 
mixed, 133-134 
type declaration, 128-129 
types 
as parameters, 137-138 
complex, 127-148 
predefined, 57-63 
variant record, 134-139 
using operators with, 76-79 
DataTest function, 133-134 
DataTest.PAS program, 139-141 
Date, reading /setting, 235-237 


DateFile.PAS program, 195-196 
DateRec function, 133-134 
Debug information option, 18 
Debugger options, 18-19 
Debugger options menu, 19 
Dec procedure, 84-85 
Decimal numerical notation, 82-83 
Declarations 

constant, 65 

scope, 66-67 

variable, 65-66 
Delay procedure, 207-208 
Delete procedure, 101-102 
Deleteltem procedure, 686-691 
DelLine procedure, 208 
Desktop option, 21-22 
Desktop Save option, 22 
Destination File option, 25 
Destination option, 39 
Destructor method, dynamic objects, 

666-670 

DetectGraph procedure, 360-361 
Devices, DOS, 161-162 
Dialog boxes 

About, 16 

Colors, 25 

Compiler Options, 17-18 

creating in Turbo Vision, 725-729 

Directories, 20 

Editor, 22 

Filename, 33-34 

Find, 25 

input line box, 728-729 

labeling clusters, 727-728 

Linker, 18-19 

Mouse options, 23 

Preferences, 20-21 

Replace, 25 

setting information, 730-731 
Direction option, 29 
Directives 

{$F+}, 337 

($I include, 284 

{$O overlay, 337-338 

compiler, 269-270 
Directories 

changing, 184 
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creating, 184-185 
creating a list, 189-191 
default, 7-9 
pathnames, 20 
removing, 185 
returning current, 185-186 
Directories dialog box, 20 
Directory options, 20 
DirTest.PAS program, 196-197 
DiskFree function (DOS), 182 
Disks, determining free space, 181-183 
DiskSize function (DOS), 182-183 
Display swapping options, 19 
Display_Directory function, 306-307 
Displays 
color, 212-217 
monochrome, 461-463 
Pop_Up Directory, 301-306 
Dispose procedure, 272-273, 666, 669- 
670 
Disposeltem procedure, 682 
DOS 
command line parameters, 
231-234 
control-break interruptions, 
239-240 
devices, 161-162 
environment information, 
237-239 
interrupt operations, 247-258 
memory organization, 266-268 
programming with, 231-242 
shell option, 35 
DosExitCode function (DOS), 247 
DosPath.BAT file, 12 
DosVersion function (DOS), 237 
Dot referencing, object-oriented pro- 
gramming, 614-615 
Draw procedure, 646-647 
DrawMultiGraphs function, 458-459 
DrawPieGraphs function, 448-454 
DrawPoly procedure, 400-401 
DRIVER.INC program, 430-431 
Drivers 
graphics, 430 
user-defined, 432-433 
DS register, returning current value, 278 
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DSeg function, 278 

DSK file extension, 25 

Dual monitor support option, 23 

Dynamic objects, 663-672 
destructor method, 666-670 
disposing of, 666 


Early binding, 618 

Edit /Copy Example command, 26 

Editor dialog box, 22 

Editor Files option, 21 

Editor heap size input box, 24 

Editor options, 22 

EGA/VGA color palette, 498 

EGA/VGA palette save option, 24 

EGA/VGA video adapter, 497-500 

Ellipse procedure, 405-406 

EMS memory, loading overlays into, 
341 

Emulation option, 18 

Encapsulation, object-oriented pro- 
gramming, 526-527 

End-of-line status, 166 

EntryStr variable, 132-133 

Enumerated data types, 61 

EnvCount function (DOS), 238 

Environ.PAS program, 241 

Environment information, DOS, 
237-239 

Environment options, 20-23 

EnvStr function (DOS), 238-239 

EOF function, 152, 166 

Eoln function, 166 

Erase procedure, 187 

EraseBlock function, 442 

EraseStr function, 439-442 

EraseThumbPad procedure, 648-649 

Error checking, text files, 151-152 

Error messages, video graphics, 
363-364 

Errors, correcting while compiling, 36 

ESC key, 26 

Evaluate option, 23 

EXE & TUP input box, 20 

EXE files, patching overlays into, 
339-340 

Exec procedure (DOS), 246-247 


Exist variable, 582-584 
Exit option, 35 
Exit procedure, 243-244 
ExitProg.PAS program, 263-264 
Exp function, 80, 85 
Expressions, 109-110 
Extended ASCII character set, 219 
Extending objects 

dot referencing, 614-615 

static method inheritance, 611-614 
External file, associating with a file 

variable, 164 


FExpand function (DOS), 188 
Fields 
data structure, 129 
referencing, 130-132 
File (F10) key, 15 
File attributes 
manipulating, 191-194 
returning, 191-192 
setting, 192 
File extensions 
CUR, 554-555 
DSK, 25 
MAP, 20 
OBJ, 20 
OVR, 339 
TPU, 20, 48, 332 
File input/output, 150-154 
File menu, 15 
File pointers, 158-159 
moving, 170 
File type, supported, 149-150 
FileAttr.PAS program, 198-199 
FileMode variable, 162-163 
Filename dialog box, 33-34 
Filenames 
expanding, 188 
splitting, 188-189 
FilePos function, 161, 167 
Files 
end-of-line status, 171 
AUTOEXEC.BAT, 9-10 
BGILINK.MAK, 429 
closing, 154, 166 
CONFIG.SYS, 6, 9 


Files (continued) 
creating /opening new, 170 
DosPath.BAT, 12 
end-of-file status, 170-171 
erasing, 187 
EXE, 339-340 
external, 164 
Frame.INC, 285 
Graph.TPU, 358-359 
HELLO.EXE, 32-33 
HELP.ZIP, 7 
include, 283-286 
locating, 187-188 
opening existing, 169-170 
Pop_Dir.INC, 285 
Pop_Up.INC, 285 
reading into variables, 168-169 
renaming, 186 
returning 
date/time stamp, 192-193 
position, 167 
size, 167 
saving, 33-34 
setting 
date/time, 192-193 
mode, 162-163 
verify flag, 194 
supported types, 149-150 
text, 150-154 
TOUR.ZIP, 7 
TPC.EXE, 7 
TPTOUR.EXE, 7 
truncating, 172 
TURBO.BAT, 12 
TURBO.EXE, 5-7 
TURBO.HLP, 7 
TURBO.TPL, 5-6, 48 
typed, 149-150, 157-161 
untyped, 149-150, 155-157 
UNZIP.EXE, 6 
verifying, 194 
writing to output, 172-173 
Files menu, 33-35 
Files/ New command, 33 
Files/Save as command, 33-34 
filesize function, 158, 167 
Fill colors, drawing, 408-411 


Fill patterns, drawing, 408-411 
FillChar procedure, 102 
FillEllipse procedure, 406 
FillPlane function, 467-468 
FillPoly procedure, 401-402 
Find dialog box, 25 
Find function, 684-685 
FindFirst procedure (DOS), 189-191 
FindNext procedure (DOS), 191 
Find Partial function, 685-686 
FIRSTGRP.PAS program, 367-373 
Flag constants, 251 
Flags 

Carry, 251-252 

CRT unit, 217-218 

register, 251-252 
Floating point operations, 62 
FloodFill procedure, 408-409 
Floppy drive system, installing Turbo 

Pascal to, 3-7 

Floppy drives, identifying types, 254 
Flush procedure, 167 
Fonts 

graphics, 431 

user-defined, 432-433 
FONTS.INC program, 431-432 
For loops, local variables with, 117 
for..to..do statement, 115-116 
Formatted strings, 96 
Frac function, 85 
Frame.INC file, 285 
FRAME.INC program, 327-328 
FRAME.PAS program, 351-352 
FreeMem procedure, 273 
Fsearch function (DOS), 187-188 
FSplit procedure (DOS), 188-189 
Functions, 46 

see also Procedures 

Abs, 83 

AddBar, 470-471 

AddData, 129 

Addr, 274 

ArcTan, 80, 84 

Bar3D, 463 

BarGraph, 454 

BlockRead, 155-157 

chr, 60, 100 


Functions (continued) 
color, 381-388 
Concat, 100-101 
ConditionalHide, 550 
Copy, 101 
Cos, 80, 84 
CreateImages, 472-474 
CRT 
KeyPressed, 103 
ReadKey, 105 
CSeg, 277-278 
CustomError, 346-347 
DataTest, 133-134 
DateRec, 133-134 
Display_Directory, 306-307 
DOS 
DiskFree, 182 
DiskSize, 182-183 
DosExitCode, 247 
DosVersion, 237 
EnvCount, 238 
EnvStr, 238-239 
FExpand, 188 
Fsearch, 187-188 
GetEnv, 239 
DrawMultiGraphs, 458-459 
DrawPieGraphs, 448-454 
DSeg, 278 
EOF, 152, 166 
Eoln, 166 
EraseBlock, 442 
EraseStr, 439-442 
Exp, 80, 85 | 
FilePos, 161, 167 
filesize, 158, 167 
FillPlane, 467-468 
Find, 684-685 
Find Partial, 685-686 
Frac, 85 
GetBkColor, 384 
GetColor, 383 
GetDefaultPalette, 386 
GetDriverName, 362 
GetGraphMode, 364 
GetImage, 413 
GetMaxColor, 381-382 
GetMaxMode, 365 
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Functions (continued) 


GetMaxX, 389-390 
GetMaxyY, 389-390 
GetModeName, 365-366 
GetName, 46 
GetPalette, 384-386 
GetPaletteSize, 386 
GetPixel, 394 
GetPosition, 547 
GetTextSettings, 425 
GetX, 390 

Get Y, 390 
GraphErrorMsg, 364 
GraphField, 465-467 
graphics text, 419-426 
GraphResult, 363 

Hi, 85-86 

image, 393-418 
ImageSize, 412 
Initialize, 551-552 
InstallUserDriver, 432-433 
InstallUserFont, 433 

Int, 86-87 

IOResult, 151-152, 167-168 
Length, 104 

line drawing, 394-395 
LineGraph, 474-476 

Ln, 80, 87 

Lo, 87 

MaxAvail, 268-269 
MemAvail, 269 
MultiBarGraph, 458-459 
object extensibility, 639-640 
Odd, 80, 87 

Ofs, 274-275 

ord, 60 

OutText 437-439 
OutTextXY, 437-439, 451 
OvrGetBuf, 342 
OvrGetRetry, 343 

page, 375-380 

palette, 381-388 
ParamCount, 232 
ParamStr, 232-234 

Pi, 80, 88 

PieGraph, 450 

PieSlice, 451 
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pixel drawing, 393-418 
Pop_Directory, 285 


Pop_Up Directory, 291-292 


Pos, 104 

Precede, 300-301 

Prt, 275-276 
QueryBtnDn, 547 
QueryBtnUp, 547-548 
Random, 80-81, 88 
Randomize, 80, 82, 88 
ReadData, 132 
ReadMove, 548 
RegisterBGIDriver, 430 
RegisterBGIFont, 431 
Reset, 544-545 

Round, 89 

screen, 375-380 

screen position, 389-392 
SeekEof, 170-171 
SeekEoln, 171 

Seg, 275 

SetAccel, 549 
SetActivePage, 379 
SetAllPallete, 496 
SetBkColor, 496 
SetCursor, 550, 552-553 
SetLimits, 545 
SetPalette, 496 
SetPosition, 546 
SetRatio, 548-549 
SetRGBPalette, 496 
SetVisualPage, 380 
Show, 545-546 
ShowAccounts, 469-470 
ShowLabels, 468-469 
Sin, 80, 89 

SPrt, 278 

Sqr, 80, 89 

Sqrt, 80, 89-90 

Swap, 90 

text, 419-426 
TextHeight, 425-426 
TextWidth, 425-426 
Trunc, 90 

UpCase, 106-107 
variable output, 437-438 
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Functions (continued) 
viewport, 375-380 
Wherex, 207 
WhereY, 207 


Get info option, 35 

GetArcCoords procedure, 406-407 
GetAspectRatio procedure, 402-403 
GetBkColor function, 384 
GetCBreak procedure (DOS), 239-240 
GetColor function, 383 

GetDate procedure, 235 
GetDefaultPalette function, 386 
GetDir procedure, 185-186 
GetDriverName function, 362 
GetEnv function (DOS), 239 
GetEquip.PAS program, 261-263 
GetExtent procedure, 711 

GetFAttr procedure (DOS), 191-192 
GetFillPattern procedure, 410-411 
GetFillSettings procedure, 411 
GetFTime procedure (DOS), 192-193 
GetGraphMode function, 364 
Getlmage function, 413 

GetIntVec procedure (DOS), 257 
GetLineSettings procedure, 397 
GetMaxColor function, 381-382 
GetMaxMode function, 365 
GetMaxxX function, 389-390 
GetMaxY function, 389-390 
GetMem procedure, 270-271 
GetModeName function, 365-366 
GetModeRange procedure, 364-365 
GetName function, 46 

GetPalette function, 384-386 
GetPaletteSize function, 386 
GetPixel function, 394 

GetPosition function, 547 
GetTextSettings function, 425 
GetTime procedure, 236 

GetVerify procedure (DOS), 194 
GetViewSettings procedure, 377 
GetX function, 390 

GetY function, 390 

Global declarations, 45 

Global variables, 615-616 

Go to cursor option, 23, 41 


GoToXY procedure, 206-207 
GRAPH unit, 358-359 
Graph.TPU file, 358-359 
GraphALL.PAS program, 477-488 
GraphDefaults procedure, 366 
GraphErrorMsg function, 364 
GraphField function, 465-467 
Graphic states/colors, 581 
Graphic Use Interface (GUD, 355 
Graphics drivers, 430 
Graphics fonts, 431 
Graphics screen save option, 24 
Graphics text function, 419-426 
Graphics, video, 355-374 
GraphResult function, 363 
Graphs 

bar, 454-458 

displaying labels, 468-469 

line, 471-476 

multiple bar, 458-461 

pie, 448-454 

three-dimensional, 463-471 

three-dimensional backgrounds 

465-467 

Gwrite procedure, 443-444 
GWRITE.INC program, 445-446 
GWriteXY procedure, 443-444 


Halt procedure, 244 

Hard drive system, installing Turbo 
Pascal to, 7-12 

Hard drives, testing for, 255 

Header, 43-44 

HeapOrg pointer, 268 

HELLO.EXE file, 32-33 

Hello2.PAS program, 223-224 

Help (F1) key, 16, 26 

Help button, 26 

Help feature, 37-38 

Help/Index command, 26 

Help menu, 26 

HELP.ZIP file, 7 

Hexadecimal numerical notation, 
82-83 

Hi function, 85-86 

HighVideo procedure, 215 


I/O routines, 163-173 


IBM 8514 
video adapter, 496-497 
video graphics card, 387-388 
Identifiers, choosing, 52-53 
if..then..else statement, 111-112 
Image functions, 393-418 
Image manipulation, 412-418 
Image options, 414-415 
ImageSize function, 412 
Inc procedure, 86 
Include directories input box, 20 
Include files 
Smart Linker with, 291 
using in source code, 283-285 
Indented code, 49-50 
Index value, 64 
InitGraph procedure, 361-362 
Initialize function, 551-552 
InitializeColors procedure, 502 
InitMenuBar procedure, 713-714 
InitOvr.PAS program, 351 
InitStatusLine procedure, 711 
Input boxes 
Conditional defines, 18 
Editor heap size, 24 
EXE & TUP, 20 
Include directories, 20 
Object directory, 20 
Overlay heap size, 24-25 
Swap file directory, 25 
Unit directories, 20 
Window heap size, 24 
Input, prompting for data, 132-133 
Insert mode option, 22 
Insert procedure, 103 
InsLine procedure, 208-209 
INSTALL program, 3-12 
InstallUserDriver function, 432-433 
InstallUserFont function, 433 
Instructions 
close, 154 
Ovrinit, 339-340 
Int function, 86-87 
INT_TEST.PAS program, 59 
INT_TST2.PAS program, 68 
Integer parameters, 98 
Integer-to-string conversion, 437 


Integer value, returning, 167-168 
Integrated Development Environment 
(IDE), 13-30 
calling, 15 
configuring, 14-16 
customizing color display, 25 
main screen, 15 
testing command line parame- 
ters, 234-235 
Integrated option, 19 
Intel 80x86 interrupts, 248-249 
Interface reserved word, 332-333 
Internal 
graphics buffer, 412 
register addresses, 277-278 
speaker, turning on/off, 221 
Interrupt operations, DOS, 247-258 
Interrupt vectors, 257-258 
DOS, 240 
Interrupts 
BIOS, 249 
calling, 252-257 
DOS operations, 247-258 
Intel 80x86, 248-249 
Intr procedure (DOS), 248 
IOResult function, 151-152, 167-168 


KeepScreen array, 287 
Key combinations 
ALT-X (Exit), 35 
ALT-F9 (Compiler), 36 
ALT-K, 16 
CTRL-BREAK (Terminate), 41 
CTRL-F1 (Help), 26, 37 
CTRL-F9 (Run), 40 
CTRL-INS (Copy), 37 
CTRL Q[ (match forward), 30 
CTRL Q] (match backward), 30 
SHIFT-INS (Edit /Paste), 37 
SHIFT-TAB, 18 
Key strokes, reporting, 290 
Keyboard, reading keystrokes, 105 
KeyPressed function (CRT), 103 
Keys 
ESC, 26 
F1 (Help), 16, 26 
F2 (Save), 35 
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F7 (Trace into), 41 
F8 (Step over), 41 
F9 (Make), 38 
F10 (File), 15 
TAB, 18 
Keywords, help, 26 


LabelColors procedure, 503 
Labels, displaying graph, 468-469 
LCD color set option, 24 
Length function, 104 
Life.PAS program, 121-126 
Lightpens, object-oriented program- 
ming, 553 

Line drawing functions, 394-395 
Line graphs, 471-476 

creating graphic images, 472-474 
Line procedure, 394-395 
LineGraf.PAS program, 488-492 
LineGraph function, 474-476 
LineRel procedure, 395 
Lines 

drawing, 394-395 

styles, 395-398 
LineTo procedure, 395 
Linked list, creating, 295-300 
Linker dialog box, 18-19 
Linking, graphics drivers and fonts, 

428-432 

LinkObj procedure, 679-680 
List 

linked, 295-300 

ordering, 300-301 
List_Entries procedure, 159-160 
Ln function, 80, 87 
Lo function, 87 
Load TURBO.TPL option, 24 
Local symbols option, 18 
Local variables, with for loops, 117 
Logical operators, 71-72, 77 
Logical.PAS program, 91-92 
Loop statements, 115-118 
Loops 

see also Statements 

local variables with, 117 

nested for, 116-117 
LowVideo procedure, 215 
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Main routing, 44-45 
Make (F9) key, 38 
Make option, 38-39 
Make utility, 429 
MakeList.PAS program, 701-702 
MAP file extension, 20 
Mark procedure, 272 
MaxAvail function, 268-269 
Mem array, 277 
Mem Avail function, 269 
MemL array, 277 
Memory 
address operators, 274-276 
allocating, 270-271 
creating new variables, 271 
deallocating, 272-273 
direct access, 277 
direct operations, 276-277 
freeing, 273-274 
loading overlays into EMS, 341 
managing usage, 268-274 
organizations, DOS, 266-268 
reporting available, 268-269 
returning in a pointer variable, 
270-271 
specifying allocation parameters, 
269-270 
Memory size options, 18-19 
MemW array, 277 
Menus 
adding to applications, 713-717 
Compiler, 40 
Compiler Options, 347-348 
Debugger options, 19 
Files, 15, 33-35 
Help, 26 
Options, 17 
pull-down, 15-16 
Run, 40 
selecting, 15-16 
System, 15-16 
Messages, unknown identifier, 49 
Methods 
see also Procedures 
ApplObj.SetColors, 726-727 
constructor, 629-631 


destructor, 666-670 
object-oriented programming, 
521-526 
SetColors, 730 
static, 618-619 
virtual object 618-619, 623-636 
MkDir procedure, 184-185 
Modes 
text display, 205-208 
video, 357-360 
Monochrome display, improving, 
461-463 
Mouse 
graphics cursors, 541-542 
implementation, 543-553 
object definitions, 542-543 
object-oriented programming, 
539-578 
problems with drivers, 539-540 
two vs. three buttons, 541 
Mouse options, 23 
Mouse options dialog box, 23 
Mouse pointer utility, 554-556 
MOUSE.PAS program, 558-578 
Move procedure, 276 
MoveRel procedure, 391 
MoveTo procedure, 390 
MsDos procedure (DOS), 248 
MultiBarGraph function, 458-459 
Multiple bar graphs, 458-461 
My_Name.PAS program, 44 
My_Name2.PAS program, 46 


Naming conventions, 50-53 
Nested for loops, 116-117 

New option, 35 

New procedure, 271, 665-666 
New window option, 21 
NewStatusKey procedure, 712 
Non-keyboard characters, 218-220 
Norm Video procedure, 215 
NoSound procedure (CRT), 221 
Nothing option, 23 

NotPut option, 415 

Numbers array, 64 

Numbers, manipulating, 69-94 


Numeric processing options, 17-18 

Numeric values, converting to a 
string, 106 

Numerical notations, 82-83 

Numerical operators, 69-73 


OB] file extension, 20 
Object declarations vs. record declara- 
tions, 517 
Object directory input box, 20 
Object extensibility, 637-662 
functions, 639-640 
procedures, 639-640 
programming for, 638-640 
tool declarations, 638-639 
Object-mouse unit, 540-542 
Object-oriented programming, 513-514 
button mouse selection, 581-582 
buttons, 556-558, 579-608 
constructor methods, 629-631 
dot referencing, 614-615 
dynamic objects, 663-372 
encapsulation, 526-527 
extending objects, 609-622 
global variables, 615-616 
inheritance, 515-518 
inheritance terminology, 521 
lightpens, 553 
methods, 521-526 
mouse, 539-578 
object data abstraction, 609-610 
object extensibility, 637-662 
organization, 527-529 
polymorphism, 529-534 
practices, 515-539 
scrollbars, 637-662 
using 
objects, 519-521 
records, 518-519 
virtual object methods, 623-636 
Objects 
allocation, 665-666 
binary tree, 673-702 
box, 584-587 
dynamic, 663-672 
extending, 609-622 
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initialization, 665-666 
object-oriented programming, 
519-521 

pointers to, 664-665 
polymorphic, 670 
returning 

address, 275 

offset, 274-275 
scrollbars, 640-651 


Odd function, 80, 87 

Offset address, converting to a pointer 
value, 275-276 

Ofs function, 274-275 

OOPTest4 program, 534-538 

Open option, 35 

Operators 


= (assignment), 76 
arithmetic, 70-71 
Boolean, 72, 77-78 
logical, 71-72, 77 
memory address, 274-276 
numerical, 69-73 
ordinal, 79-80 
relational, 74-75, 78-79 
set, 74 

string, 73-76 

using with data, 76-79 


Optimal fill option, 22 
Options 


see also Commands 
Evaluate, 23 

8087 /80287, 17-18 

Add watch, 23 

AndPut, 415 

Auto Save, 21 
Autoindent mode, 22 
Backspace unindents, 22 
Breakpoint, 23 

Build, 38-39 

case sensitive, 29 

CGA snow checking, 24 
Change dir, 34 

code generation, 17-18 
colors, 25 

Compile, 36 

Compiler, 17, 38-39 


Options (continued) 
Config File Directory, 22 
configuration, 16-20 
CopyPut, 414 
create backup files, 22 
Current Directory, 22 
Current window, 21 
Cursor Mask, 554 
cursor through tabs, 22 
Debug, 19 
debug information, 18-19 
Desktop, 21-22 
Desktop Save, 22 
Destination, 39 
Destination File, 25 
Direction, 29 
directory, 20 
display swapping, 19 
DOS shell, 35 
Dual monitor support, 23 
editor, 22 
Editor Files, 21 
EGA/VGA palette save, 24 
Emulation, 18 
environment, 20-23 
Exit, 35 
Files menu, 35 
Get info, 35 
Go to cursor, 23, 41 
Graphics screen save, 24 
Image, 414-415 
Insert mode, 22 
Integrated, 19 
LCD color set, 24 
Load TURBO.TPL, 24 
Local symbols, 18 
Make, 38-39 
memory size, 18-19 
mouse, 23 
New, 35 
New window, 21 
Nothing, 23 
NotPut, 415 
numeric processing, 17-18 
Open, 35 
Optimal fill, 22 
Origin, 29 
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Options (continued) 
OrPut, 414-415 
Parameters, 41 
Pop_Up Directory display, 
302-306 
Preferences, 20-21 
Primary file, 25, 39 
Print, 35 
Program reset, 41 
Prompt on replace, 29 


Range checking, 18 
Regular expression, 29 
Retrieve, 25-26 
Runtime errors, 18 
Save, 25-26, 35 

Save as, 33-34 

Scope, 29 


Screen Mask, 555 
Search/Replace, 29 
selecting, 18 
Smart, 19 
Source tracking, 21 
Standalone, 19 
Startup, 23-25 
Step over, 41 
syntax, 18 
Tab size, 22 
Topic search, 23 
Trace into, 41 
Use expanded memory, 24 
Use tab character, 22 
Whole words only, 29 
XOrPut, 414 
Options menu, 17 
ord function, 60 
Ordinal 
data types, 58-60 
operators, 79-80 
value, changing into a character, 
100 
Origin option, 29 
OrPut option, 414-415 
Output, screen, 95-100 
Output utilities, 439-442 
OutText function, 437-439 
OutText procedure, 420 
OutTextXY function, 437-439, 451 
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OutTextXY procedure, 420-421 
Overlay heap size input box, 24-25 
Overlay, initializing manager, 340-341 
Overlay unit, 335-336 
Overlays 

calling, 336-337 

clearing buffer, 342 

compiling units, 336 

custom handler, 346-347 

debugging, 339 

manager, 335-336 

operations, 331-354 

patching into EXE files, 339-340 

profiling, 339 

programming, 335-336 

restrictions, 338-339 

result codes, 343 

returning current buffer size, 342 

setting buffer size, 341-343 

with initialization sections, 

337-338 

OVR file extension, 339 
OvrClearBuf procedure, 342 
OvrFileMode variable, 344 
OvrGetBuf function, 342 
OvrGetRetry function, 343 
Ovrinit instruction, 339-340 
Ovrinit procedure, 340-341 
OvriInitEMS procedure, 341 
OvrLoadCount variable, 344 
OvrRead Buf variable, 344-346 
OvrReadFunc variable, 344-345 
OvrResult variable, 343 
OvrSetBuf procedure, 341-342 
OvrSetRetry procedure, 342-343 
OvrTrapCount variable, 344 


PackTime procedure (DOS), 193 
Page functions, 375-380 
Pair matching, Turbo Editor, 29 
Palette functions, 381-388 
ParamCount function, 232 
Parameters 

boolean, 99-100 

character, 97 

data types as, 137-138 

DOS command line, 231-234 


integer, 98 

passing by address, 53-55 

real, 98-99 

reporting number passed to pro- 

gram, 232 

string, 97-98 
Parameters option, 41 
ParamStr function, 232-234 
Parent directory specification (..\), 34 
Parent.PAS program, 258-259 
Parentheses (), in dialog boxes, 17 
Parenthesis /asterisk (**) characters, 47 
ParmTest.PAS program, 240-241 
Pascal file types, 149-150 
PATH statement, modifying during 

installation, 9-12 

Pathnames, directory, 20 
PhonTree.PAS program, 694-701 
Pi function, 80, 88 
Pie graphs, 448-454 

exploded, 454 
PieGraph function, 450 
PieSlice function, 451 
PieSlice procedure, 407-408 
Pixel drawing functions, 393-418 
Pointer variable 

recording heap state, 272 

returning heap state, 272 
Pointers 

data, 292-295 

HeapOrg, 268 

mouse, 554-556 

object, 664-665 

tracking records with, 292-295 
Polygons, drawing, 398-402 
Polymorphic objects, 670 
Polymorphism 

create method, 530-531 

destroy method, 532-533 

object-oriented programming, 

529-534 

SetColor method, 532-533 
Pop_Demo.PAS program, 309 
Pop_Dir.INC file, 285 
Pop_Dir.INC program, 310-326 
Pop_Directory function, 285 
Pop_Up Directory display, 301-306 





Pop_Up Directory function, 291-292 
Pop_Up.INC file, 285 
POP_UP.INC program, 328-329 
Pop_Up.PAS program, 349-350 
Pop_Up2.PAS program, 352 
Pos function, 104 
Precede function, 300-301 
Predefined streams, 161-162 
Preferences dialog box, 20-21 
Preferences option, 20-21 
PrefixSeg variable, 266 
Primary file option, 25, 39 
Print option, 35 
PrintList procedure, 682-683 
Procedures, 46 
see also Functions; Methods 
object extensibility, 639-640 
Procedures InitMenuBar, 713-714 
Program, installing, 3-12 
Program reset option, 41 
Programmer comments, 47 
Programming 
event-driven, 704-705 
object-oriented, 513-514 
overlays, 335-336 
Programs 
anatomy of, 43-56 
ASCII format, 32 
comment identifiers, 48 
comments, 47-48 
compiling, 36-37 
creating, 31-42 
delaying execution, 207-208 
entering, 33 
executing, 40-41, 246 
global declarations, 45 
header, 43-44 
indented code, 49-50 
INSTALL, 3-12 
interrupting, 243-246 
main routine, 44-45 
naming conventions, 50-53 
OOPTest4, 534-538 
parameters, 53-55 
reserved words, 44-45, 52 
saving, 33-34 
subroutines, 45-48 
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Programs (continued) 
terminating execution, 41 
units, 48-49 
writing source code, 31-32 

Prompt on replace option, 29 

Prt function, 275-276 

Pseudo-random algorithm, 81 

PtrView variable, 727-728 

Pull-down menus, 15-16 

PUT-DEMO.PAS program, 415-418 

Putlmage procedure, 413-414 

PutPixel procedure, 393-394 


QueryBtnDn function, 547 
QueryBtnUp function, 547-548 


Radio buttons 

in dialog boxes, 17 

selecting options, 19 

Turbo Vision, 724 
Random function, 80-81, 88 
Random numbers, 81-83 
Randomize function, 80, 82, 88 
Range checking option, 18 
Read procedure, 168-169 
Read_Dir.PAS program, 199-201 
Read_Directory procedure, 292-295 
Read_Screen procedure, 288-290 
ReadData function, 132 
ReadDate procedure, 137 
Reading screens, 288-290 
ReadKey function (CRT), 105 
ReadLn procedure, 106, 169 
ReadMove function, 548 
ReadScr1.PAS program, 330 
READSCR2.PAS program, 349 
READSCR3.PAS program, 350-351 
ReadText.PAS program, 174 
Real data types, 58, 61 
Real parameters, 98-99 
Real-to-string conversion, 437-438 
Record declarations vs. object declara- 

tions, 517 

Record structure, data elements, 128 
Record types, registers, 250-251 
Record variants, defining, 134-139 


Records 
Check2.PAS, 144-148 
object-oriented programming, 
518-519 
reading into a variable, 165 
tracking with pointers, 292-295 
writing into a variable, 165-166 
Rectangle procedure, 398 
Rectangles, drawing, 398-402 
RegisterBGIDriver function, 430 
RegisterBGIFont function, 431 
Registers 
AX, 252 
CH,.285 
CL, 253 
CS, 277-278 
DS, 278 
flags, 251-252 
SP, 278 
Registers record type, transferring 
data to CPU, 250-251 
Regular expression option, 29 
Relational operators, 74-75, 78-79 
Relative pathname, 20 
Release procedure, 272 
Remove_Item procedure, 306-307 
Rename procedure, 186 
repeat..until statement, 118 
Replace button, 35 
Replace dialog box, 25 
Replace operations, 29 
Reserved words, 44-45, 52 
interface, 332-333 
Reset function, 544-545 
Reset procedure, 169-170 
Restore_Screen procedure, 286-290 
RestoreCrtMode procedure, 367 
Restore ViewPort procedure, 645 
Result variable, 156 
Retrieve options, 25-26 
Retrieve Options command, 25 
Rewrite procedure, 170 
RmDir procedure, 185 
Round function, 89 
Routines, 1/O, 163-173 
Run menu, 40 


Run/Run command, 40-41 
RunError procedure (DOS), 245 
RunError.PAS program, 260-261 
Runtime errors options, 18 


Save (F2) key, 35 
Save as option, 33-34 
Save options, 25-26, 35 
Save Options command, 25 
Save_Record procedure, 158-159 
Save_Screen procedure, 286-290 
Scope 

declaration, 66-67 

exercise in, 292 

with Pop_Up Directory function, 

292-292 

Scope option, 29 
Screen functions, 375-380 
Screen Mask options, 555 
Screen position functions, 389-392 
Screens 

clearing, 208 

deleting lines, 208 

erasing text display, 209 

IDE main, 15 

inserting lines, 208-209 

output, 95-100 

position, setting, 206-207 

reading, 288-290 

sizes, selecting display, 20-21 
ScrlBar.PAS program, 655-660 
ScrlTest.PAS program, 661-662 
ScrlTst2.PAS program, 671-672 
Scrollbars 

constructor, 644-645 

creating, 641-644 

object-oriented programming, 

637-662 

omissions, 652-653 
ScrollHit procedure, 649-651 
Search/Find command, 29 
Search operations, 29 
Search/Replace command, 29 
Search/ Replace options, 29 
Search strings, 29 
Searches, binary tree, 683-686 
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seek command, 158 
Seek procedure, 170 
SeekEof function, 170-171 
SeekEoln function, 171 
Seg function, 275 
Semicolon (;), as statement terminator, 
110 
Set operators, 74 
SetAccel function, 549 
SetActivePage function, 379 
SetAllPalette function, 496 
SetBkColor function, 496 
SetBkColor procedure, 383-384 
SetCBreak procedure (DOS), 240 
SetColor procedure, 382-383 
SetColors method, 730 
SetCursor function, 550, 552-553 
SetDate procedure, 235-236 
SetFAttr procedure (DOS), 192 
SetFillPattern procedure, 409-410 
SetFillStyle procedure, 410 
SetFTime procedure (DOS), 193 
SetGraphBufSize procedure, 412 
SetGraphMode procedure, 366-367 
SetIntVec procedure (DOS), 257-258 
SetLimits function, 545 
SetLineStyle procedure, 396-397 
SetLoc procedure, 645-646 
SetPalette function, 496 
SetPalette procedure, 386-387 
SetPosition function, 546 
SetRatio function, 548-549 
SetRBGPalette procedure, 388 
SetRGBPalette function, 496 
SetTextBuf procedure, 171-172 
SetTextJustify procedure, 422-424, 502 
SetTextStyle procedure, 421-422, 502 
SetThumbPad procedure, 648 
SetTime procedure, 236-237 
SetUserCharSize procedure, 424 
Set Verify procedure (DOS), 194 
Set ViewPort procedure, 376-377 
Set VisualPage function, 380 
SetWriteMode procedure, 397-398 
Short-circuit evaluation, 73 
Show function, 545-546 
ShowAccounts function, 469-470 


ShowColors procedure, 502 
ShowLabels function, 468-469 
ShowMem.PAS program, 279-281 
Simple data types, 58 
Sin function, 80, 89 
Smart linker, 49, 204, 427-428 
with include files, 291 
Smart option, 19 
Sound procedure (CRT), 221 
SoundEff.PAS program, 227-230 
Source code 
using include files, 283-285 
writing, 31-32 
Source tracking option, 21 
SP register, returning current value, 
278 
Speakers, turning on/off, 221 
SPrt function, 278 
Sqr function, 80, 89 
Sqrt function, 80, 89-90 
Standalone option, 19 
Startup options, 23-25 
Statement terminator (;), 110 
Statements, 109-110 
{$I-}, 151-152 
{SI+}, 151-152 
begin..end, 110-111 
case..of, 112-114 
conditional, 111-115 
DOS, PATH, 9-12 
for..to..do, 115-116 
grouping a series, 111 
if..then..else, 111-112 
loop, 115-118 
repeat..until, 118 
switch decisions, 114-115 
while not..do, 152 
while..do, 117-118, 152 
with..do, 130-132 
Static methods 
compiler operations, 616-618 
redefined as virtual methods, 628 
vs. virtual methods, 618-619 
Step over (F8) key, 41 
Step over command, 40-41 
Step over option, 41 
StepColors procedure, 502, 504 


Str procedure, 106 
Streams, predefined, 161-162 
Strings 
concatenating, 100-101 
for output, 438-439 
constants, 67 
data 
formatting, 97 
types, 62-63 
expressing length, 104 
inserting substrings, 103 
manipulating, 95-108 
operator, 73-76 
parameters, 97-98 
removing substrings, 101-102 
returning, 106 
substrings, 101 
searching for substrings, 104 
unformatted vs. formatted, 96 
writing to screen, 95 
Structured programming, 45 
Structures, data, 128 
Subdirectories, default, 7-9 
Subrange data types, 61 
Subroutines, 45-48 
testing, 118-119 
Substrings 
inserting into strings, 103 
removing from a string, 101-102 
returning from a string, 101 
searching for, 104 
Swap file directory input box, 25 
Swap function, 90 
SwapVectors procedure (DOS), 247 
Syntax options, 18 
System 
date/time, reading, 235-237 
memory, working with, 265-282 
menu, 15-16 
video attributes, 493 


TAB key, 18 

Tab size option, 22 

TBoxes unit, 582-586 
TBoxes.PAS program, 600-605 


Terminating carriage return character 
(ODh), 153 
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TestDays.PAS program, 92-93 
Text buttons, states/colors, 580-581 
Text 

array, 64 

color constants, 214 


combining with graphics, 435-446 


display, editing, 208-209 
files, 149-154 
appending, 154 
assigning I/O buffer, 171- 
172 
associating with the CRT 
(console), 164 
error checking, 151-152 
opening for input, 150-151 
opening for output, 152 
reading input, 152-153 
reopening existing, 163 
writing output, 153 
justification, 421-424 
modes, 205-208 
setting, 206 
selecting display size, 20-21 
settings information, 424-426 
sizing, 421-424 
styles, 421-424 
Text functions, 419-426 
Text windows, 209-211 
TextAttr variable, 212, 215-217 
TextBackground procedure, 215 
TextColor procedure, 214-215 
TextHeight function, 425-426 
TextMode command, 206 
TextWidth function, 425-426 
ThisApp variable, 709-710 
Three-dimensional graphs, 463-471 
Time, reading /setting, 235-237 
Tool declarations, object extensibility, 
538-639 
Topic search option, 23 
TOUR.ZIP file, 7 
TPC.EXE file, 7 
TPTOUR.EXE file, 7 
TPU file extension, 20, 48, 332 
Trace into (F7) key, 41 
Trace into command, 40-41 
Trace into option, 41 


Trunc function, 90 
Truncate procedure, 172 
Turbo Editor commands, 27-28 
Turbo Editor 
pair matching, 29 
search/replace operations, 29 
Turbo Pascal 
as graphics-oriented language, 
353-354 
installing, 3-12 
Turbo Tour utility, 7 
Turbo Vision 
adding features to applications, 
710-713 
adding menus to applications 
713-717 
constraints, 705-706 
creating applications, 708-710 
dialog box data record, 725 
event-driven programming, 
704-705 
frameworks vs. toolbox, 709-710 
introduction, 703-706 
radiobuttons, 724 
setting colors, 723-724 
toolbox, 704 
toolbox vs. frameworks, 709-710 
TURBO, BAT file, 12 
TURBO.EXE file, 5-7 
TURBO.HLP file, 7 
TURBO. TPL file, 5-6, 48 
Tutorials 
Turbo Tour, 7 
starting, 7 
TVDemo02.PAS program, 718-719 
TVDemo03.PAS program, 719-721 
TVDemo04.PAS program, 732-740 
TVDemol1.PAS program, 718 
Type declaration, data structure, 
128-129 
Typecasting conversions, 59-60 
Typed files, 149-150, 157-161 
random access, 160-161 
reading from, 159-160 
writing to, 158-159 


Unary operators, 69-70 


Unformatted strings, 96 
Unit directories input box, 20 
Units, 48-49 
buttons, 586-593 
compiling for overlays, 336 
creating, 332 
CRT 203-205 
GRAPH, 358-359 
implementation section, 333-334 
initialization section, 334-335 
interface section, 332-333 
object-mouse, 540-542 
operations, 331-354 
TBoxes, 582-586 
UnpackTime procedure (DOS), 
193-194 
Untyped files, 149-150, 155-157 
UNZIP.EXE file, 6 
UpCase function, 106-107 
Use expanded memory option, 24 
Use tab character option, 22 
User-defined 
drivers, 432-433 
fonts, 432-433 
Utilities 
Make, 429 
mouse pointer, 554-556 
output, 439-442 
Turbo Tour, 7 


Values, integer, 167-168 
Variable declarations, 65-66 
Variable output functions, 437-438 
Variables 

BlankLine, 450-451 

Buffer, 155-156 

BufSize, 155-156 

Count, 156 

creating new memory, 271 

CRT unit, 217-218 

EntryStr, 132-133 

Exist, 582-584 

FileMode, 162-163 

global, 615-616 

OvrFileMode, 344 

OvrLoadCount, 344 

OvrRead Buf, 344-346 
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Variables (continued) 
OvrReadFunc, 344-346 
OvrResult, 343 
OvrTrapCount, 344 
pointer, 272 
PrefixSeg, 266 
PrtView, 727-728 
Result, 156 
TextAttr, 212, 215-217 
ThisApp, 709-710 
Wind Max, 218 
Wind Min, 218 

Variant record types, 134-139 

Vectors 
DOS interrupt, 240 
interrupt, 257-258 

Verify flag, setting file, 194 

VGA video adapter, 496-500 

Vid_Text.PAS program, 222-223 

Video aspect ratio, 402-403 

Video graphics 
adapter types, 357-358 
advanced procedures, 427-434 
automatic erasure, 443-444 
business graphic displays, 447-492 
CGA adapter, 494-496 
CGA color values, 494 
changing pixel colors, 393-394 
color relations cube, 500-506 
color values, 385 
combining with text, 435-446 
concatenating strings for output, 

438-439 
creating drivers and fonts, 429 
determining type, 360-361 
drawing 
arcs, 403-408 
bar graphs, 398-402 
circles, 403-408 
curves, 403-408 
fill colors, 408-411 
fill patterns, 408-411 
lines, 394-395 
polygons, 398-402 
rectangles, 398-402 
drivers, 430 





EGA/VGA video adapter, 
497-500 
erasing screen, 375-376 
error messages, 363-364 
fonts, 431 
IBM-8514, 387-388 
adapter, 496-497 
image manipulation, 412-418 
initialing graphic error codes, 362 
internal graphics buffer, 412 
introduction to, 355-374 
line styles, 395-398 
linking drivers and fonts, 428-432 
multiple pages, 377-380 
naming current graphics driver, 
362, 364 
output utilities, 439-442 
programming disadvantages, 358 
programming for, 356 
redefining palettes, 386-387 
resetting system video, 367 
resetting to default values, 366 
returning 
color palette index, 394 
current background color, 
384 
current graphics window, 
377 
maximum valid color num- 
ber, 381-382 
mode name, 365-366 
mode number, 365 
palette definition record, 386 
palette size, 386 
selecting 
background color, 383-384 
drawing color, 382-383 
foreground color, 382-383 
new mode, 366-367 
page for active display, 379- 
380 
setting 
active viewport, 376-377 
palette colors, 384-386 
parameters, 361-362 
specifying driver, 364-365 


text 
fonts, 421 
functions, 419-426 
justification, 421-424 
settings information, 424- 
426 
sizing, 421-424 
styles, 421-424 
user-defined fonts /drivers, 
432-433 
VGA video adapter, 496-500 
video aspect ratio, 402-403 
video signal cues, 493-494 
Video modes, 205-208, 357-358 
supported types, 359-360 
Video signal cues, 493-494 
Viewport functions, 375-380 
Virtual Method Table, 623-628 
Virtual object methods 
creating, 628-631 
range checking, 631 
Virtual Method Table, 623-628 
vs. static methods, 618-619 


Weekday2.PAS program, 120-121 
Weekdays.PAS program, 120 
WhereX function, 207 
WhereY function, 207 
while not..do statement, 152 
while..do statement, 117-118, 152 
Whole words only option, 29 
WindMax variable, 218 
WindMin variable, 218 
Window heap size input box, 24 
Window.PAS program, 224-227 
Windows 

displaying multiple, 210-211 

limits, 209 

opening new, 21 

text, 209-211 
with..do statement, 130-132 
Words, reserved, 52 
write procedure, 95-96, 159, 172-173 
WriteLn procedure, 95-96, 173 
WriteName procedure, 46 


XOrPut option, 414 
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